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.
|