Skip to content

Latest commit

 

History

History
115 lines (77 loc) · 5.29 KB

CONTRIBUTING.md

File metadata and controls

115 lines (77 loc) · 5.29 KB
Raw

Contributing to this project

This information is heavily based on this CONTRIBUTING.md document.

Before making a contribution, please take a moment to review this document. It will make the process easier and more enjoyable for everyone involved.

Following the guidelines in this document shows that you respect the time of the maintainers of this open-source project. In return, maintainers should show their respect for you by addressing your requests, issues, and contributions in a timely fashion.

Submitting issues

GitHub’s built-in issue tracker is the preferred channel for bug reports, feature requests, and submitting pull requests.

Do not use the issue tracker for personal support questions. They will probably not be addressed. Do not derail or troll issues. Please try to keep things on topic and be respectful to others.

Bug reports

Demo or it didn’t happen.

A bug is a problem that you can demonstrate to a maintainer on this open-source project. Good bug reports are very helpful, and encouraged!

If you are thinking about reporting a bug, please do the following:

  1. Search for existing issues - it could have already been reported.
  2. Check for fixes - try to reproduce the bug using the latest release on the master branch in the repository.
  3. If the bug persists, submit an issue and create a live example of the bug using a public service like jsFiddle or Codepen. Link to your example in the issue that you submit.

Please be as detailed as possible. Ask yourself: What is your environment? What steps will reproduce the issue? What browser(s) and OS experience the problem? What would you expect to be the outcome?

Feature requests

Feel free to request whatever you like, but please take a moment to think about whether your request is within the scope of the project. You should make a strong case for your request, otherwise the maintaining developers will probably not consider it. Provide as much detail as you can.

Pull requests

Good pull requests are awesome. Bad pull requests are a headache. They should always be limited by the scope of the request, and avoid including unrelated commits.

Please file an issue first before deciding to do a lot of work. Otherwise, you run the risk of wasting time working on something that might not get merged into the project.

Follow this process if you’d like your work to be considered for inclusion in the project:

  1. Fork the project, clone your fork, and configure the remotes:

    # Clone your fork of the repo into the current directory
git clone https://github.com/<your-username>/cardinal
# Navigate to the newly cloned directory
cd cardinal
# Assign the original repo to a remote called "upstream"
git remote add upstream https://github.com/cbracco/cardinal

  2. If you cloned a while ago, get the latest changes from upstream:

    git checkout master
git pull upstream master

  3. Never work directly on master. Create a new topic branch (off the latest version of master) to contain your feature, change, or fix:

    git checkout -b <topic-branch-name>

  4. Commit your changes in logical chunks. Please adhere to these git commit message conventions or your code is unlikely be merged into the main project. Use Git’s interactive rebase feature to tidy up your commits before making them public.

    Please add a test to the test.html file if appropriate, and test your change(s) in all supported browsers.

  5. Locally rebase the upstream development branch into your topic branch:

    git pull --rebase upstream master

  6. Push your topic branch up to your fork:

    git push origin <topic-branch-name>

  7. Open a Pull Request with a clear title and description.

IMPORTANT: By submitting a patch, you agree to allow the project owner to license your work under the same license as that used by the project.

Maintainers

If you have commit access, please follow this process for merging patches and cutting new releases.

Accepting patches

  1. Check that a patch is within the scope and philosophy of the project.
  2. Check that a patch has any necessary tests and a proper, descriptive commit message.
  3. Test the patch locally.
  4. Do not use GitHub’s merge button. Apply the patch to master locally (either via git am or by checking the whole branch out). Amend minor problems with the author’s original commit if necessary. Then push to GitHub.

Releasing a new version

  1. Run gulp to compile CSS assets, and use a dedicated commit for these changed files.
  2. Add all new functional changes into the CHANGELOG.
  3. Use a dedicated commit to increment the version. The version needs to be added to the CHANGELOG.md (inc. date), and package.json files.
  4. The commit message must be of v0.0.0 format.
  5. Create an annotated tag for the version: git tag -m "v0.0.0" 0.0.0.
  6. Push the changes and tags to GitHub: git push --tags origin master