Skip to content

Latest commit

 

History

History
129 lines (90 loc) · 4.79 KB

CONTRIBUTING.md

File metadata and controls

129 lines (90 loc) · 4.79 KB
Raw

Contribution Guide

Thank you for coming here! It's always nice to have third-party contributors 🤗

Submitting code

  1. If you want to add/edit/remove code, first, open an issue.
  2. Every issue, has gets it's own branch in the same repo, generally forked from main-dev.
  3. If you want your every commit displayed and discussed, push right there.
  4. If you want to work on something privately, fork it under your own username.
  5. For your Pull Request to pass a review, submit not just the code, but also the tests, and the documentation.

Git Credentials

Mark sure your email is set. Github can hide your real email for you.

  • git config --global user.email "YOUR_EMAIL"

Branches

  • main for last stable version.
  • main-dev to synchronize the development.
  • ##-feature branch per issue number.
  • v1.0.0-like branch per LTS version.

Commits

  • Subject (top) line is up to 50 characters.
    • Should continue the sentence: "This commit will ...".
    • Shouldn't end with a period.
    • Must start with a "verb" or "type" or "tag".
    • May mark the programming language in broad projects.
  • Description lines are optional and limited to 72 characters.
    • Use the body to explain what and why vs. how. Code already answers the latter.
    • If relevant, reference the issue at the end, using the hashtag notation.
  • If a commit can't be described with a single verb, it should be split into parts.

The template would be:

<type>: <description>

[optional body]

[optional footer(s)]

An example would be:

Fix: Short (50 chars or less) summary

More detailed explanatory text. Wrap it to 72 characters. The blank
line separating the summary from the body is critical (unless you omit
the body entirely).

Write your commit message in the imperative: "Fix bug" and not "Fixed
bug" or "Fixes bug." This convention matches up with commit messages
generated by commands like git merge and git revert.

Further paragraphs come after blank lines.

- Bullet points are okay, too.
- Typically a hyphen or asterisk is used for the bullet, followed by a
  single space. Use a hanging indent.

Commit Verbs

We agree on a short list of leading active verbs for the subject line, similar to the ESLint convention.

Verbs Part When?
Refactor - Non-user facing changes
Test - Updates only to tests
Docs - Updates only to documentation
Build - Compilation fixes
Make patch New compilation settings, or configs
Fix patch Bug fixes
Improve patch Small enhancement
Upgrade patch Updating a dependency version
Add minor New feature
Breaking major Backwards-incompatible update

Which is a well known, widely adopted set, and self-explanatory set.

Why Use Conventional Commits?

  • Automatically generating CHANGELOGs.
  • Automatically determining a semantic version bump (based on the types of commits landed).
  • Communicating the nature of changes to teammates, the public, and other stakeholders.
  • Triggering build and publish processes.
  • Making it easier for people to contribute to your projects, by allowing them to explore a more structured commit history.

Automated Semantic Versioning

  • Every repo has a root level VERSION file.
  • Contents are major.minor.patch followed by newline.
  • CI tools will automatically generate a CHANGELOG.md and release notes.

We use a variation of Semantic Versioning.

Conventional Commits specification.

Libraries and Dependencies

  • Check that your licenses are compatible.
  • Prefer dependencies, that are actively maintained, tested, and documented.
  • Prefer projects using the same build system.

Choosing dependencies is much harder than it seems. Those rules can be skipped or bended. For example, many teams may not consider using projects with less than 1'000 stars on GitHub. Yet some of the cleanest and coolest repositories I have seen, have exactly zero stars. Being cautious is a good baselines, but if you want to be competitive, you have to take risks.

Code

  • No trailing whitespaces.
  • Every file must end with newline.