Developer Guidelines

Version Control

All our projects use Git, mostly with a repository hosted on GitHub. Since we're a small team, and most projects have less than 3 people working on it simultaneously, we have pretty loose Git guidelines since we rarely bump into conflicts.

Repo naming conventions

If the repo contains the source code of a site its name should be the main naked domain name of that site. It should be lowercased.

  • Bad: https://www.zaengle.com, www.zaengle.com
  • Good: zaengle.com

Sites that are hosted on a subdomain may use that subdomain in their name

  • Bad: zaengle.com-guidelines
  • Good: guidelines.zaengle.com

If the repo concerns something else, for example a package, its name should be kebab-cased.

  • Bad: LaravelBackup, Spoon
  • Good: laravel-backup, spoon

Branches

If you're going to remember one thing in this guide, remember this: Once a project has gone live, the master branch must always be stable. It should be safe to deploy the master branch to production at all times. All branches are assumed to be active; stale branches should get cleaned up accordingly.

We attempt to follow GitFlow which you may read more about here.

Projects in initial development

Projects that aren't live yet have at least two branches: master and develop. Avoid committing directly on the master branch, always commit through develop.

Work is broken into manageable chunks and a new feature branch is cut from develop to contain the work. Do not create feature branches from master.

Live projects

Once a project goes live, all future commits to master must be added through either a release branch, which should be tagged according to the version number, or from a new hotfix branch.

There's no strict ruling on feature branch names, just make sure it's clear enough to know what they're for. Branches may only contain lowercase letters and hyphens.

  • Bad: mailchimp, random-things, develop
  • Good: feature/mailchimp, feature/fix-deliverycosts or feature/updates-june-2016

If a live project requires a staging environment, create a staging branch that deploys automatically when new code is pushed. Ideally the develop branch will be reserved for passing code back and forth between developers on the project and should not auto-deploy.

Releases

When preparing a release, cut a new branch from develop named something like releases/1.1.5. Make any necessary commits, such as compiling production assets or updating the changelog, and merge into both production and develop, tagging it with the appropriate version number.

Optionally, before merging into production you may choose to push the release branch to the staging branch in order to test it on the staging environment.

Pull requests

Merging branches via GitHub pull requests isn't a requirement in every situation*, but can be useful if:

  • You want a peer to review your changes
  • You want to ensure your branch can be merged and commits can be squashed via an interface
  • Future you wants a quick way to retrieve that point in history by browsing passed pull requests

Once you've opened a PR, tag a coworker and tech lead as reviewers. Until your PR is either merged or closed it is your responsibility to follow up with change requests made by the reviewer(s).

After addressing feedback either with discussion or code changes "resolve conversation" via GitHub interface.

*It's best to use the PR workflow unless you've been specifically cleared to merge your own work by a tech lead.

Merging and rebasing

Ideally, rebase your feature branch regularly to reduce the chance of merge conflicts, especially prior to merging into develop or creating a new PR.

Commits

There's not strict ruling on commits in projects in initial development, however, descriptive commit messages are recommended. After a project has gone live, descriptive commit messages are required. Always use present tense in commit messages.

  • Non-descriptive: wip, commit, a lot, solid
  • Descriptive: Updates deps, Fixes tax calculation in delivery costs

Ideally, prefer granular commits.

  • Acceptable: Cart fixes
  • Better: Fixes add to cart button, Fixes cart count on home

Git Tips

Creating granular commits with patch

If you've made multiple changes but want to split them into more granular commits, use git add -p. This will open an interactive session in which you can choose which chunks you want to stage for your commit.

Resources

← Syntax Formatting →