| 1 | # Contributing
|
| 2 |
|
| 3 | We love pull requests. Here's a quick guide.
|
| 4 |
|
| 5 | ### 1. Fork, then clone the repo:
|
| 6 |
|
| 7 | git clone git@github.com:jpettersson/lingon.git
|
| 8 |
|
| 9 | ### 2. Install dependencies:
|
| 10 |
|
| 11 | npm install
|
| 12 |
|
| 13 | ### 3. Make sure the tests pass:
|
| 14 |
|
| 15 | You want to be sure that everything is A-OK before starting work on your feature.
|
| 16 |
|
| 17 | ./test.sh
|
| 18 |
|
| 19 |
|
| 20 | ### 4. Write Documentation
|
| 21 |
|
| 22 | The Lingon contributors practise README driven development. Add your changes to the documentation before writing code. This will put you in a happy place where you contemplate about how real users will interact with your change.
|
| 23 |
|
| 24 | If your change affects the stable Lingon API, update ``docs/API.md``<br />
|
| 25 | If your change affects how a user interacts with Lingon, update ``docs/USAGE.md``
|
| 26 |
|
| 27 | ### 5. Write your feature
|
| 28 |
|
| 29 | Ok, so now you can write some code. Have fun!
|
| 30 |
|
| 31 | ### 6. Add tests for your feature. Make the tests pass:
|
| 32 |
|
| 33 | ./test.sh
|
| 34 |
|
| 35 | ### 7. Briefly describe your change in the CHANGELOG.md file under HEAD
|
| 36 |
|
| 37 | This makes sure we announce the change in the next release.
|
| 38 |
|
| 39 | ### 8. Push to your fork and [submit a pull request][pr].
|
| 40 |
|
| 41 | [pr]: https://github.com/jpettersson/lingon/compare/
|
| 42 |
|
| 43 | TravisCI will run the test suite and let you know that you've done and awesome job. If travis says A-OK, your work is done for now. At this point you're waiting on us. We like to at least comment on pull requests
|
| 44 | within two business days (and, typically, one business day). We may suggest
|
| 45 | some changes or improvements or alternatives. We promise to respond to all PRs.
|
| 46 |
|
| 47 | # Releasing
|
| 48 |
|
| 49 | The following is a guide describing the Lingon release process. The text is targeted towards Lingon contributors with merge/publish privileges.
|
| 50 |
|
| 51 | ## Releasing a patch
|
| 52 |
|
| 53 | A patch is a change that addresses some flaw or issue in either the Lingon source code or the documentation.
|
| 54 |
|
| 55 | * A patch MUST not add new functionality.
|
| 56 | * A patch SHOULD be tested.
|
| 57 |
|
| 58 | ### 1. Find a bug
|
| 59 |
|
| 60 | You have found a bug (from usage or a bug issue).
|
| 61 |
|
| 62 | * If an issue exist, self assign to signal that you are working on this.
|
| 63 | * If no issue exists you should create one.
|
| 64 |
|
| 65 | ### 2. Write the test, then fix the bug
|
| 66 |
|
| 67 | First, reproduce the bug locally and create a system or unit test that can catch it. Then proceed with writing a fix.
|
| 68 |
|
| 69 | ### 3. Update HEAD in changelog
|
| 70 |
|
| 71 | Add an entry to the changelog HEAD section so explain what you have fixed.
|
| 72 |
|
| 73 | ### 4. Push to master & wait for Travis OK
|
| 74 |
|
| 75 | Push your change to master and wait for Travis to confirm that everything is OK.
|
| 76 |
|
| 77 | ### 5. Create a review release tag & test manually
|
| 78 |
|
| 79 | * Update the version in package json to signal a review release. Use the format: `2.0.0-review1`.
|
| 80 | * Create a tag with the same name: `2.0.0-review1` and push it.
|
| 81 | * Manually test the review release in your favorite Lingon project.
|
| 82 | * Invite others to test if you are extra paranoid.
|
| 83 |
|
| 84 | This step can be skipped if you have a high confidence in that the patch will NOT break anything else.
|
| 85 |
|
| 86 | ### 6. Publish to NPM
|
| 87 |
|
| 88 | * Increment the version to the next patch: For instance, `2.0.1`.
|
| 89 | * Publish to NPM
|
| 90 |
|
| 91 | ## Releasing a feature (minor release)
|
| 92 |
|
| 93 | ### 1. Select a feature
|
| 94 |
|
| 95 | Self assign one of the the `planned-feature` issues (create one if it does not exist).
|
| 96 |
|
| 97 | ### 2. Write feature & tests
|
| 98 |
|
| 99 | Work on a branch and write a feature.
|
| 100 |
|
| 101 | * Include good test covereage of the new feature
|
| 102 | * Include relevant documentation for the feature
|
| 103 | * Include a CHANGELOG entry for the feature
|
| 104 |
|
| 105 | ### 3. Send a PR
|
| 106 |
|
| 107 | When the feature is done, or you want feedback, create a PR.
|
| 108 |
|
| 109 | ### 4. Wait for at least 1 other person to approve
|
| 110 |
|
| 111 | Discuss the feature with at least 1 other Lingon maintainer before mergin. Common practise is that you never merge your own feature. Instead, ask someone else to review and merge for you.
|
| 112 |
|
| 113 | ### 5. Sync with team
|
| 114 |
|
| 115 | Sync the release of features with the other Lingon maintainers. Ideally we should batch some changes up and not release every single feature as it's own minor.
|
| 116 |
|
| 117 | ## Releasing a breaking change (major release)
|
| 118 |
|
| 119 | Let's not do that! No, but seriously.. we try to avoid this as much as possible. Because of this, it's not a process to be defined in a document. We'll have a conversation about it.
|