Skip to content

Latest commit

 

History

History
170 lines (126 loc) · 6.67 KB

CONTRIBUTING.md

File metadata and controls

170 lines (126 loc) · 6.67 KB

Contributing

Table of content

1.Git

The purposes of a unified git workflow is:

  • Define branches role
  • Ensure branches have the appropriate code
  • Ensure branches states - mainly keep master deployable at any time

1.1 Some Git Rules

There are a set of rules to keep in mind:

  • Perform work in a feature or fix branch.

    Why:

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.

  • Never push into master or develop branches. 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 a forum for discussing the proposed feature.

  • Delete local and remote feature/fix 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 (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 chances of formatting fixes being mingled in with actual changes.

1.2 Gitflow workflow

For a complete comprehension of gitflow workflow, please refer to this Atlasian's guide . Briefly:

  • The master branch contains released code and is tagged with release version.
  • The develop branch, created from master, contains developed code for next release.
  • The feature or fix branches contain code under development. When development is done, the code is put on develop via a pull request.

How to proceed

  • Checkout a new feature/fix branch.

    git checkout -b <branchname>

    Branch name should follow this template feature/<feature-name> or fix/<issue-number>.

  • 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

  • Push your branch.

    git push

  • Make a Pull Request.

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

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

    git branch -d <branchname>

1.3 Writing good commit messages

  • 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 th 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.

  • Capitalize the subject line.

  • Do not end the subject line with a period.

  • Use imperative mood in the subject line.

    Why:

    Rather than writting messages that say what a commiter has done. It's better to consider these messages as the instruction for what is going to be done after the commit is applied on the repository.

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

2.Documentation

  • 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.

3.Dependencies

  • Keep track of your currently available packages

  • See if any of your packages have become unused or irrelevant.

    Why:

    You may include an unused library in your code and increase the production bundle size. Find unused dependencies and get rid of them.

  • Before using a dependency, check its download statistics to see if it is heavily used by the community.

    Why:

    More usage mostly means more contributors, which usually means better maintenance, and all of these result in quickly discovered bugs and quickly fixes.

  • Before using a dependency, check to see if it has a good, mature version release frequency with a large number of maintainers.

    Why:

    Having loads of contributors won't be as effective if maintainers don't merge fixes and patches quickly enough.

  • If a less known dependency is needed, discuss it with the team before using it.

  • Always make sure your app works with the latest version of its dependencies without breaking.

  • Check to see if the package has known security vulnerabilities with, e.g., Snyk

4.Testing

  • Write testable code, avoid side effects, extract side effects, write pure functions.

    Why:

    You want to test a business logic as separate units. You have to "minimize the impact of randomness and nondeterministic processes on the reliability of your code".

    A pure function is a function that always returns the same output for the same input. Conversely, an impure function is one that may have side effects or depends on conditions from the outside to produce a value. That makes it less predictable.

  • Run test locally before making any pull requests to develop.

  • Document your tests including instructions in the relevant section of the README.md file.

5.Structure and Naming

6.Code style

The styles used for this project are: