Skip to content

Latest commit

 

History

History
121 lines (73 loc) · 4.67 KB

CONTRIBUTING.md

File metadata and controls

121 lines (73 loc) · 4.67 KB

Project Guidelines

1. Git

1.1 Some Git rules

There are a set of rules to keep in mind:

  • Perform work in a feature branch.

    Why:

    Because this way all work is done in isolation on a dedicated branch rather than the main branch. It allows you to submit multiple pull requests without confusion. You can iterate without polluting the master branch with potentially unstable, unfinished code. read more...

  • Branch out from develop

    Why:

    This way, you can make sure that code in master will almost always build without problems, and can be mostly used directly for releases.

  • Never push into develop or main branch. Make a Pull Request.

    Why:

    It notifies team members that they have completed a feature. It also enables easy peer-review of the code and dedicates forum for discussing the proposed feature.

  • Delete local and remote feature branches after merging.

    Why:

    It will clutter up your list of branches with dead branches. It ensures you only ever merge the branch back into (main or develop) once. Feature branches should only exist while the work is still in progress.

  • Before making a Pull Request, make sure your feature branch builds successfully and passes all tests (including code style checks).

    Why:

    You are about to add your code to a stable branch. If your feature-branch tests fail, there is a high chance that your destination branch build will fail too. Additionally, you need to apply code style check before making a Pull Request. It aids readability and reduces the chance of formatting fixes being mingled in with actual changes.

1.2 Git workflow

  • Sync with remote to get changes you’ve missed.

    git checkout develop
git pull

  • Checkout a new feature/bug-fix branch.

    git checkout -b <branchname>

  • Make Changes.

    git add <file1> <file2> ...
git commit

    Why:

    git add <file1> <file2> ... - you should add only files that make up a small and coherent change.

    git commit will start an editor which lets you separate the subject from the body.

    Read more about it in section 1.3.

    Tip:

    You could use git add -p instead, which will give you chance to review all of the introduced changes one by one, and decide whether to include them in the commit or not.

  • Make a Pull Request to develop.

  • Pull request will be accepted, merged and close by a reviewer.

  • Remove your local feature branch if you're done.

    git branch -d <branchname>

    to remove all branches which are no longer on remote

    git fetch -p && for branch in `git branch -vv --no-color | grep ': gone]' | awk '{print $1}'`; do git branch -D $branch; done

1.3 Writing good commit messages

Having a good guideline for creating commits and sticking to it makes working with Git and collaborating with others a lot easier. Here are some rules of thumb (source):

  • Separate the subject from the body with a newline between the two.

    Why:

    Git is smart enough to distinguish the first line of your commit message as your summary. In fact, if you try git shortlog, instead of git log, you will see a long list of commit messages, consisting of the id of the commit, and the summary only.

  • Limit the subject line to 50 characters and Wrap the body at 72 characters.

    why

    Commits should be as fine-grained and focused as possible, it is not the place to be verbose. read more...

  • Capitalize the subject line.

  • Do not end the subject line with a period.

  • Use imperative mood in the subject line.

    Why:

    Rather than writing messages that say what a committer has done. It's better to consider these messages as the instructions for what is going to be done after the commit is applied on the repository. read more...

  • Use the body to explain what and why as opposed to how.

2. Documentation

  • Keep README.md updated as a project evolves.
  • Comment your code. Try to make it as clear as possible what you are intending with each major section.
  • If there is an open discussion on GitHub or stackoverflow about the code or approach you're using, include the link in your comment.
  • Don't use comments as an excuse for a bad code. Keep your code clean.
  • Don't use clean code as an excuse to not comment at all.
  • Keep comments relevant as your code evolves.