Skip to content

Latest commit

 

History

History
94 lines (64 loc) · 5.61 KB

CONTRIBUTING.md

File metadata and controls

94 lines (64 loc) · 5.61 KB
Raw

How to contribute

One of the easiest ways to contribute is to participate in discussions and discuss issues. You can also contribute by submitting pull requests with code changes.

General feedback and discussions?

Please start a discussion on the Home repo issue tracker.

Filing issues

When filing issues, please use our issue templates. The best way to get your bug fixed is to be as detailed as you can be about the problem. Providing a minimal project with steps to reproduce the problem is ideal. Here are questions you can answer before you file a bug to make sure you're not missing any important information.

  1. Did you include the snippet of broken code in the issue?
  2. What are the EXACT steps to reproduce this problem?
  3. What package versions are you using?
  4. What operating system are you using?

GitHub supports markdown, so when filing bugs make sure you check the formatting before clicking submit.

Contributing code and content

Make sure you can build the code. Familiarize yourself with the project workflow and our coding conventions. If you don't know what a pull request is read this article: https://help.github.com/articles/using-pull-requests.

Before submitting a feature or substantial code contribution please discuss it with the team and ensure it follows the product roadmap. You might also read these two blogs posts on contributing code: Open Source Contribution Etiquette by Miguel de Icaza and Don't "Push" Your Pull Requests by Ilya Grigorik. Note that all code submissions will be rigorously reviewed and tested by the Cole team, and only those that meet an extremely high bar for both quality and design/roadmap appropriateness will be merged into the source.

Commit/Pull Request Format

Summary of the changes (Less than 80 chars)
 - Detail 1
 - Detail 2

Addresses #bugnumber (in this specific format)

Tests

  • Tests need to be provided for every bug/feature that is completed.
  • If there is a scenario that is far too hard to test there does not need to be a test for it.
  • "Too hard" is determined by the team as a whole.

Contribution Workflow

You can contribute to Cole Core with issues and PRs. Simply filing issues for problems you encounter is a great way to contribute. Contributing implementations is greatly appreciated.

For complete instructions on how to compile see: Building From Source

For quickly compiling and testing your changes do:

# For building.
make build

./bin/cole

Suggested Workflow

We use and recommend the following workflow:

  1. Create an issue for your work.
    • You can skip this step for trivial changes.
    • Reuse an existing issue on the topic, if there is one.
    • Get agreement from the team and the community that your proposed change is a good one.
    • Clearly state that you are going to take on implementing it, if that's the case. You can request that the issue be assigned to you. Note: The issue filer and the implementer don't have to be the same person.
  2. Create a personal fork of the repository on GitHub (if you don't already have one).
  3. Create a branch off of master (git checkout -b mybranch).
    • Name the branch so that it clearly communicates your intentions, such as issue-123 or githubhandle-issue.
    • Branches are useful since they isolate your changes from incoming changes from upstream. They also enable you to create multiple PRs from the same fork.
  4. Make and commit your changes.
  5. Add new tests corresponding to your change, if applicable.
  6. Build the repository with your changes.
    • Make sure that the builds are clean.
    • Make sure that the tests are all passing, including your new tests.
  7. Create a pull request (PR) against the upstream repository's development branch.
    • Push your changes to your fork on GitHub (if you haven't already).

Note: It is OK for your PR to include a large number of commits. Once your change is accepted, you will be asked to squash your commits into one or some appropriately small number of commits before your PR is merged.

Note: It is OK to create your PR as "[WIP]" on the upstream repo before the implementation is done. This can be useful if you'd like to start the feedback process concurrent with your implementation. State that this is the case in the initial PR comment.

PR - CI Process

The continuous integration (CI) system will automatically perform the required builds and run tests (including the ones you are expected to run) for PRs. Builds and test runs must be clean.

If the CI build fails for any reason, the PR issue will be updated with a link that can be used to determine the cause of the failure.

PR Feedback

Cole team and community members will provide feedback on your change. Community feedback is highly valued. You will often see the absence of team feedback if the community has already provided good review feedback.

1 or more Cole team members will review every PR prior to merge. They will often reply with "LGTM, modulo comments". That means that the PR will be merged once the feedback is resolved. "LGTM" == "looks good to me".

There are lots of thoughts and approaches for how to efficiently discuss changes. It is best to be clear and explicit with your feedback. Please be patient with people who might not understand the finer details about your approach to feedback.