|
| 1 | + |
| 2 | +# Welcome to the create-nteract-app contributing guide! |
| 3 | +We are _thrilled_ you want to contribute to create-nteract-app! Below you will find guidance on how you can jump in and help out :tada: |
| 4 | + |
| 5 | +[Code of Conduct](#code-of-conduct) |
| 6 | + |
| 7 | +[Questions about create-nteract-app?](#questions-about-create-nteract-app) |
| 8 | + |
| 9 | +[How to Contribute](#how-to-contribute) |
| 10 | +- [What do I need to know to help?](#what-do-i-need-to-know-to-help) |
| 11 | +- [How to make a contribution](#how-to-make-a-contribution) |
| 12 | +- [How should I write my commit messages and PR titles?](#how-should-i-write-my-commit-messages-and-pr-titles) |
| 13 | + |
| 14 | +## Code of Conduct |
| 15 | +First and foremost, nteract is an inclusive organization. This project and everyone participating in it is governed by the [nteract Code of Conduct ](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to [[email protected]](mailto:[email protected]). |
| 16 | + |
| 17 | +## Questions about create-nteract-app |
| 18 | +Feel free to post issues on GitHub or chat with us in [Slack](https://nteract.slack.com/) ([request an invite](https://slack.nteract.io/)) if you need help or have |
| 19 | +questions. If you have trouble creating an account on Slack, either email |
| 20 | +[email protected] or post an issue on GitHub. |
| 21 | + |
| 22 | +## How to Contribute |
| 23 | + |
| 24 | +### What do I need to know to help |
| 25 | +You'll need knowledge of JavaScript (ES6), React and Next.js to help out with this project. That's a whole lot of cool stuff! But don't worry, we've got some resources to help you out. |
| 26 | + |
| 27 | +- [Kent C. Dodd](https://github.com/kentcdodds)'s beginner guide to React course on [egghead.io](https://egghead.io/courses/the-beginner-s-guide-to-react) |
| 28 | +- [Learning to build a simple Next.js app](https://nextjs.org/learn/) |
| 29 | + |
| 30 | +### How to make a contribution |
| 31 | +Never made an open source contribution before? Wondering how contributions work |
| 32 | +in the nteract world? Here's a quick rundown! |
| 33 | + |
| 34 | +1. Find an issue that you are interested in addressing or a feature that you would like to address. |
| 35 | +2. Fork the repository associated with the issue to your local GitHub username or organization. |
| 36 | + |
| 37 | + ___Note___: if you are already a member of the nteract organization, it's not necessary to fork create-nteract-app to contribute -- you can clone create-nteract-app and push your branch directly to the create-nteract-app repo. |
| 38 | +3. Clone the repository to your local machine using: |
| 39 | + |
| 40 | + git clone https://github.com/github-username/create-nteract-app.git |
| 41 | + |
| 42 | +4. Create a new branch for your fix using: |
| 43 | + |
| 44 | + git checkout -b branch-name-here |
| 45 | + |
| 46 | +5. Make the appropriate changes for the issue you are trying to address or the feature that you want to add. |
| 47 | +6. Confirm that unit tests and linting still pass successfully with: |
| 48 | + |
| 49 | + node src/index.js snow-leopard && yarn test |
| 50 | + |
| 51 | + If tests fail, don't hesitate to ask for help. |
| 52 | + |
| 53 | +7. Add and commit the changed files using `git add` and `git commit`. |
| 54 | +8. Push the changes to the remote repository using: |
| 55 | + |
| 56 | + git push origin branch-name-here |
| 57 | + |
| 58 | +9. Submit a pull request to the upstream repository. |
| 59 | +10. Title the pull request per the requirements outlined in the section below. |
| 60 | +11. Set the description of the pull request with a brief description of what you |
| 61 | + did and any questions you might have about what you did. |
| 62 | +12. Wait for the pull request to be reviewed by a maintainer. |
| 63 | +13. Make changes to the pull request if the reviewing maintainer recommends |
| 64 | + them. |
| 65 | +14. Celebrate your success after your pull request is merged! :tada: |
| 66 | + |
| 67 | +### How should I write my commit messages and PR titles |
| 68 | + |
| 69 | +Good commit messages serve at least three important purposes: |
| 70 | + |
| 71 | +* To speed up the reviewing process. |
| 72 | + |
| 73 | +* To help us write a good release note. |
| 74 | + |
| 75 | +* To help the future maintainers of nteract/nteract (it could be you!), say |
| 76 | + five years into the future, to find out why a particular change was made to |
| 77 | + the code or why a specific feature was added. |
| 78 | + |
| 79 | +Structure your commit message like this: |
| 80 | + |
| 81 | +``` |
| 82 | +> Short (50 chars or less) summary of changes |
| 83 | +> |
| 84 | +> More detailed explanatory text, if necessary. Wrap it to about 72 |
| 85 | +> characters or so. In some contexts, the first line is treated as the |
| 86 | +> subject of an email and the rest of the text as the body. The blank |
| 87 | +> line separating the summary from the body is critical (unless you omit |
| 88 | +> the body entirely); tools like rebase can get confused if you run the |
| 89 | +> two together. |
| 90 | +> |
| 91 | +> Further paragraphs come after blank lines. |
| 92 | +> |
| 93 | +> - Bullet points are okay, too |
| 94 | +> |
| 95 | +> - Typically a hyphen or asterisk is used for the bullet, preceded by a |
| 96 | +> single space, with blank lines in between, but conventions vary here |
| 97 | +> |
| 98 | +``` |
| 99 | +*Source: http://git-scm.com/book/ch5-2.html* |
| 100 | + |
| 101 | +#### DO |
| 102 | + |
| 103 | +* Write the summary line and description of what you have done in the |
| 104 | + imperative mode, that is as if you were commanding. Start the line |
| 105 | + with "Fix", "Add", "Change" instead of "Fixed", "Added", "Changed". |
| 106 | +* Always leave the second line blank. |
| 107 | +* Line break the commit message (to make the commit message readable |
| 108 | + without having to scroll horizontally in gitk). |
| 109 | + |
| 110 | +#### DON'T |
| 111 | + |
| 112 | +* Don't end the summary line with a period - it's a title and titles don't end |
| 113 | + with a period. |
| 114 | + |
| 115 | +#### Tips |
| 116 | + |
| 117 | +* If it seems difficult to summarize what your commit does, it may be because it |
| 118 | + includes several logical changes or bug fixes, and are better split up into |
| 119 | + several commits using `git add -p`. |
| 120 | + |
| 121 | +#### References |
| 122 | + |
| 123 | +The following blog post has a nice discussion of commit messages: |
| 124 | + |
| 125 | +* "On commit messages" http://who-t.blogspot.com/2009/12/on-commit-messages.html |
| 126 | + |
| 127 | +#### How fast will my PR be merged? |
| 128 | + |
| 129 | +Your pull request will be merged as soon as there are maintainers to review it |
| 130 | +and after tests have passed. You might have to make some changes before your |
| 131 | +PR is merged but as long as you adhere to the steps above and try your best, |
| 132 | +you should have no problem getting your PR merged. |
| 133 | + |
| 134 | +That's it! You're good to go! |
0 commit comments