Skip to content

Latest commit

 

History

History
172 lines (121 loc) · 6.26 KB

CONTRIBUTING.md

File metadata and controls

172 lines (121 loc) · 6.26 KB
Raw

Contributing

We would love for you to contribute to aerie-ui and help make it even better than it is today! As a contributor, here are the guidelines we would like you to follow:

Got a Question or Problem?

If you would like to chat about the question in real-time, you can reach out via our slack channel.

Submitting a Pull Request (PR)

Before you submit your Pull Request (PR) consider the following guidelines:

  1. Search GitHub for an open or closed PR that relates to your submission. You don't want to duplicate effort.
  2. Be sure that an issue describes the problem you're fixing, or documents the design for the feature you'd like to add. Discussing the design up front helps to ensure that we're ready to accept your work.
  3. Clone the Aerie/aerie-ui repo.
  4. Make your changes in a new git branch: 
    git checkout develop
git pull origin develop
git checkout -b my-fix-branch develop
  5. Create your patch.
  6. Follow our Coding Rules.
  7. Commit your changes using a descriptive commit message that follows our commit message conventions. Adherence to these conventions is necessary because release notes are automatically generated from these messages. 
    git commit -a
    Note: the optional commit -a command line option will automatically "add" and "rm" edited files.
  8. Push your branch to GitHub: 
    git push origin my-fix-branch
  9. In GitHub, send a pull request to aerie-ui:develop.

  • If we suggest changes, then:

    • Make the required updates.

    • Follow our Coding Rules.

    • Rebase your branch and force push to your branch to GitHub (this will update your Pull Request):

      git rebase develop -i
git push -f

  • If your PR branch gets out of date, please rebase off of the latest on the develop branch using one of two following ways:

    • Via git commands (this is no different from the above step), rebase your branch and force push to your branch to GitHub:

      git rebase develop -i
git push -f

    • Via github, there should be an "Update branch" button at the bottom of your PR. Select the dropdown arrow and choose "Update with rebase" instead. After selecting it, then go ahead and click the "Update with rebase" button to rebase off of the latest on develop

Once your PR has been approved, it is preferred to "Squash and merge" to keep the commits on develop a little cleaner and easier to search through (commit message guideliness). Before, you squash, please remember to update the commit message body to only include what is relevant. (NOTE: Do NOT update the PR title as that will mess up some tracking)

After your pull request is merged, you can safely delete your branch and pull the changes from the repository:

  • Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows:

    git push origin --delete my-fix-branch

  • Check out the develop branch:

    git checkout develop

  • Update your develop with the latest version:

    git pull origin develop

  • Delete the local branch:

    git branch -D my-fix-branch

Coding Rules

Run the following commands to execute formatting, linting, static analysis, and testing:

  1. npm run format:write
  2. npm run lint
  3. npm run lint:css
  4. npm run check
  5. Follow the testing procedures in the testing documentation

Commit Message Guidelines

We have very precise rules over how our git commit messages can be formatted. This leads to more readable messages that are easy to follow when looking through the project history.

Commit Message Format

Each commit message consists of a header and a body. The header has a special format that includes a type and a subject:

<type>: <subject>
<BLANK LINE>
<body>

The header is mandatory.

Any line of the commit message cannot be longer 100 characters! This allows the message to be easier to read on GitHub as well as in various git tools.

Samples:

docs: update readme

fix: need to depend on latest rxjs and zone.js

The version in our package.json gets copied to the one we publish, and users need the latest of these.

(more samples)

Revert

If the commit reverts a previous commit, it should begin with revert:, followed by the header of the reverted commit. In the body it should say: This reverts commit <hash>., where the hash is the SHA of the commit being reverted.

Type

Must be one of the following:

  • build: Changes that affect the build system or external dependencies
  • ci: Changes to our CI configuration files and scripts
  • docs: Documentation only changes
  • feat: A new feature
  • fix: A bug fix
  • perf: A code change that improves performance
  • refactor: A code change that neither fixes a bug nor adds a feature
  • release: A release commit
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  • test: Adding missing tests or correcting existing tests

Subject

The subject contains a succinct description of the change:

  • use the imperative, present tense: "change" not "changed" nor "changes"
  • don't capitalize the first letter
  • no dot (.) at the end

Body

Just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes". The body should include the motivation for the change and contrast this with previous behavior.

Breaking Changes should start with the word BREAKING CHANGE: with a space or two newlines. The rest of the commit message is then used for this.