🚰 workflow & collaboration

or, the "working with others" part. (even if that other person is just your future self trying to understand WTF your code does years later).

i ❤ giti ❤ git

tl;dr

repository

git

git is the way we’ll save code and how we can enable collaborating with others in the future. GitHub has become almost synonymous with git as its most widely used implementor of the technology.

first, initialize a repository:

git init [projectname]

basic commands

  • git help [command] — for help on any particular command. or just git help.
  • git clone [url] — copy a repository to your local machine.
  • git status — get the state of your repository.
  • git pull — get the latest state of your repository from the central repository.
  • git push — push out your changes to the central repository.
    • git pull --rebase — i tend to use the --rebase flag to not have thousands of “merge” commits in history.
  • git log — show the history of the repository. optionally, you can specify a branch name.
    • git log --stat — a more detailed view into the log.
  • git branch — manage different versions of your repository.
    • git branch -D — delete the branch.
  • git add [file] — add a particular file to the pending commit.
  • git reset [file] — remove a file from the pending commit.
  • git mv \[orig\] [dest] — move a file in your repository.
  • git rm [file] — remove a file from your repository.
  • git commit — create an entry with your latest work.
    • add -a to add all current files.
  • git checkout [branch] — switch to another branch.
    • git checkout -b [branch] — create the branch.
  • git checkout [file] — checkout the original copy of the file.
  • git diff — show differences made to the current branch.
    • git diff > patch.diff — to create a diff of your current branch.
    • patch -p[0|1] patch.diff — to apply your previously saved patch.
  • git revert [commit hash] — undo a particular commit.
  • git stash — to put away your current work temporarily. super handy.
    • git stash pop — to retrieve the work you stashed.
    • git stash drop — to throw away your changes.

if you installed zsh and oh-my-zsh (from the +🛠️ tools of the trade chapter) then you’ll have some handy dandy shortcuts in your shell already, check them out here:

cat ~/.oh-my-zsh/plugins/git/git.plugin.zsh


# my commonly used ones are:
gst # git status
gb  # git branch
gc  # git commit
gco # git checkout
gd  # git diff
gp  # git push

other useful commands

  • git grep [pattern] — search for files that match a particular pattern.
  • git bisect — enables a for a bug regression in your codebase by checking out previous versions of your project in piecemeal fashion.
  • git show [commit hash] — show a particular commit or object.
  • git cherry-pick [commit hash] — grab a commit from another branch.
    • especially useful when trying to hotfix a production branch.
  • git rebase / merge — merge work with others.
    • probably the hardest part of dealing with a repository.
    • you should read up more on this before using.
    • as noted above you can use git pull --rebase to make your workflow somewhat easier.
  • git ls-files — list out the files in your repository. use with grep to be useful.
  • git blame [file] — useful to see the history of each line in a file.
  • git reflog — useful in case you think you lost some work accidentally. you probably didn’t.
    • read the docs for more info on how to use and get your work back.
  • git config --global push.default current — so you don’t have to do --set-upstream all the time.

for bigger teams you might consider looking at You can combine packages like Commitizen and Semantic Release to help you with versioning and maintaining a changelog.

pull requests

  • squash and merge: recommend to use squashing so that all the many commits from individual PRs don’t pollute the main branch’s git history.

gui’s

if you’re into this sort of thing (and your editor/IDE doesn’t support repository manipulation), you can look at standalone applications:

signing

for an extra verification layer for your commits, you can sign your commits via GPG. NOTE: on OS X you’ll need to follow some extra steps to hack around it not working 😕

package management

npm is your tool to enable you to install work from others on the internet. why invent the wheel and there are probably already 14 packages that have done it for you!

first, initialize npm in your git repository: (reference)

npm init

answer the questions and you should get package.json at the end of it. next, install the packages you need via these commands:

npm install [package]


# or, to specify a dependency type
npm install --save\[dev|prod|optional\] [package]
npm install --production [package]    # to install on prod

to uninstall a package:

npm uninstall [package]

alternatively, there is also yarn, which is pretty much equivalent to npm these days.

tips

  • as a security precaution, use --save-exact to ensure your package doesn’t get updated without auditing behind your back (not to mention making the package version consistent with others on your team)
  • use npm-check-updates (or ncu) to keep your packages up-to-date.
    • a great visual way to run ncu is: ncu --interactive --format group,repo

directory structure

a good structure for your project lays out the initial strokes to make organizing your small project to (maybe) one day be a larger project. this template is just one way of doing things but can be a great way to kick off your project.

editor consistency

also, using something like .gitattributes can be useful to make sure things like line-endings are consistent. e.g.:

* text=auto eol=lf

security

  • git secrets: ensure secrets don’t get committed to code

multi-package

if you have a larger organization/multiple projects under the same umbrella, do check out turborepo or nx. both have great tools. these tools are the next generation after things like Lerna.

collaboration

with yourself

this sounds silly, right? but you may be your own worst enemy sometimes when it comes to getting shit done. because coding is an inherently creative exercise, it requires being able to set aside time to get into the state of flow (or, “in the zone”). here’s a list of things to help you focus on the task at hand:

  • email:
    • once/twice a day: your physical mail comes once a day at your house’s mailbox, you process it and move on with your life. go through your email in the morning and maybe after lunch, close that tab, and move on. if people need to get to you faster they can get you through IM/Slack.
    • filters: aggressively create filters to hide unimportant emails.
    • never on weekends: YOLO as the kids say.
    • inbox zero (or maybe inbox four 🙂): go through your inbox and respond, delete, delegate, or defer. YMMV on this — some people love it, some people think it’s an excessively strict philosophy that sets one up for failure.
  • maker time:
    • block off time on your calendar: put blocks of time on your calendar stating “maker time” or “do not schedule”. this is especially true as you grow in your career and responsibilities.
    • no meeting wednesday: this worked great at my previous company. it meant no one could schedule meetings which created a culture of maker time. i would argue thursday should also be no meetings, too, but that was a tough sell.
    • one late night a week: having a solid chunk of time to get into that flow state is crucial. work out with yourself and/or partner to give yourself time to work uninterrupted.
    • one/two weeks a year to experiment: if you can afford it, give yourself time to blow off steam during the year to experiment and learn something different. your work/company probably will benefit from it!
  • headphones: a great signal to others to leave you alone to your work. let others know this if it’s not understood.
  • hide: i’m only half-kidding. 😛

if you want to go deeper on this topic you can take a look at this more in-depth look at "Deep Work”.

with others

there’s lots of ways to collaborate with others. sometimes it can be a bit much but it’s useful to learn the different tools!

tools

  • email: obviously. use for lower latency communication, i.e. 24 hour response would be ok.
  • irc: for quick communication. the kids are all into it these days in the form of Slack.
  • wiki: Dropbox Paper. (i’m biased because i worked on this before. 😇) write down your tribal knowledge that’s floating around in people’s heads. Notion is also well loved.
  • issue tracker/planning: Linear is well-loved and gotten a lot of traction.
  • issue tracker: GitHub issue tracker.
  • diagrams: diagrams.net.
  • AVOID: if you see Jira on a startup’s list of tools, run away, run away! 👻

methodology

  • agile: basically, anything but waterfall will get you where you want to be going. a cadence of 6-weeks from idea to launch is probably good time for things to bake but can vary for your team and project. check out this takeaway on how Spotify scaled agile at their company with the concept of tribes, squads, chapters, and guilds. here’s a comparison of various workflows.
  • RACI framework: figure out who is Responsible, Accountable, Consulted, and Informed. this helps give clarity to of ownership in a project. an overview is found here.

consistency

to preserve sanity with others you work with, pick a coding style and stick with it.

npm install prettier --save-dev --save-exact
npm install lint-staged husky --save-dev
# add to package.json
"husky": {
    "hooks": {
    "pre-commit": "lint-staged"
    }
},
"lint-staged": {
    "src/**/*.{js,jsx,ts,tsx,json,css,scss,md}": [
    "prettier --single-quote --write",
    "git add"
    ]
},
  • versioning: Semantic Versioning. when creating a new version of your app try to use consistent versioning.
  • language: using a tool like alex can help make sure you are using equitable, fair, and inclusive language.

documentation

some would say that this section would come first. in some ways they’re right, since documentation tends to unfortunately be an afterthought for a lot of projects. lucky for you there are some tools to get over that ugh-can’t-someone-else-do-this-inertia.

  • Docusaurus: use Markdown and React to create your project’s docs.
  • Read the Docs: use Markdown and CLI to generate your project’s docs.

for an inspirational view into how one company open-sourced their documentation check out Artsy:

website

the ever classic way to get visibility and get your product out there is creating a site. an easy way to do this is to take advantage of GitHub Pages. it’ll let you quickly let you get a page up for your project.

support

various ways to show love for your work these days:

newbies

if you have someone new to the team, you would do well to:

  • help them get setup on their laptop
  • show them documentation
  • hook them up with communication access (slack, email, etc.)
  • super important: commit code the first day!! have some trivial task that has the newbie commit code even if it’s just adding their name to an about page. this will probably tick a lot of boxes in getting them setup.

a word on open source

just do it. to paraphrase Bill Murray: "oh, uh, there won't be any money, but when you die, on your deathbed, you will receive total consciousness." so you’ll have that goin’ for you, which is nice.

healthy contribution

take a look at this great breakdown from GitHub. then, take a look again. this stuff is important.

special files in your repo

special github-specific files in your repo

continuous integration / continuous deployment (CI/CD)

as your team grows, it will seem that the velocity of your project will slow. part of this is inevitable as you have more communication and coordination to help enable. but, you can help keep some of that speed by using a CI server to allow your developers to continually push new features to your app without fear (mostly) that they will take down production.

the recommendation here is Github Actions. to get started on how Github Actions works i recommend looking at Github Actions By Example for a quick primer.

other products in this space are Travis CI. i also hear good things about is Danger JS, which adds common code review chores to GitHub pull requests.

staging / canary servers

if you have the ability to do so, a staging or canary server is highly recommended. this is a server that you can use internally to “dogfood” your application before it goes out to the general public. testing can catch a lot of things but sometimes new classes of errors can only crop up with real-world use.

💿 db☕ javascript