|
| 1 | +# Contributing |
| 2 | + |
| 3 | +We are very interested in receiving feedback on these materials, particularly |
| 4 | +from anybody who has attended the course. |
| 5 | + |
| 6 | +## How to Contribute |
| 7 | + |
| 8 | +The easiest way to get started is to file an issue to tell us about a spelling |
| 9 | +mistake, some awkward wording, or a factual error. |
| 10 | + |
| 11 | +1. If you have a [GitHub][github] account, or are willing to [create |
| 12 | + one][github-join], but do not know how to use Git, you can report problems |
| 13 | + or suggest improvements by [creating an issue][issues]. This allows us to |
| 14 | + assign the item to someone and to respond to it in a threaded discussion. |
| 15 | + |
| 16 | +2. If you are comfortable with Git, and would like to add or change material, |
| 17 | + you can submit a pull request (PR). Instructions for doing this are |
| 18 | + [included below](#using-github). |
| 19 | + |
| 20 | +## Where to Contribute |
| 21 | + |
| 22 | +1. If you wish to change this lesson, |
| 23 | + please work in <https://github.com/ImperialCollegeLondon/grad_school_git_course>, |
| 24 | + which can be viewed at <https://imperialcollegelondon.github.io/grad_school_git_course>. |
| 25 | + |
| 26 | +## What to Contribute |
| 27 | + |
| 28 | +There are many ways to contribute, from writing new exercises and improving |
| 29 | +existing ones to updating or filling in the documentation and submitting [bug |
| 30 | +reports][issues] about things that don't work, aren't clear, or are missing. If |
| 31 | +you are looking for ideas, please see the 'Issues' tab for a list of issues |
| 32 | +associated with this repository. |
| 33 | + |
| 34 | +Comments on issues and reviews of pull requests are just as welcome: we are |
| 35 | +smarter together than we are on our own. Reviews from novices and newcomers are |
| 36 | +particularly valuable: it's easy for people who have been using these lessons |
| 37 | +for a while to forget how impenetrable some of this material can be, so fresh |
| 38 | +eyes are always welcome. |
| 39 | + |
| 40 | +If you would like to propose new content or exercises please make sure to create |
| 41 | +an issue and get the thoughts of the maintainers. Please try to bear in mind |
| 42 | +that any new material must be compatible with Windows, macOS and Linux. |
| 43 | + |
| 44 | +## Using GitHub |
| 45 | + |
| 46 | +If you choose to contribute via GitHub, you may want to look at [How to |
| 47 | +Contribute to an Open Source Project on GitHub][how-contribute]. To manage |
| 48 | +changes, we follow [GitHub flow][github-flow]. This lesson is maintained by the |
| 49 | +Research Software Engineering team at Imperial College, who will review and |
| 50 | +approve any contributions. To use the web interface for contributing to a |
| 51 | +lesson: |
| 52 | + |
| 53 | +1. Fork the originating repository to your GitHub profile. |
| 54 | +2. Within your version of the forked repository, move to the `gh-pages` branch |
| 55 | + and create a new branch for each significant change being made. |
| 56 | +3. Navigate to the file(s) you wish to change within the new branches and make |
| 57 | + revisions as required. |
| 58 | +4. Commit all changed files within the appropriate branches. |
| 59 | +5. Create individual pull requests from each of your changed branches |
| 60 | + to the `gh-pages` branch within the originating repository. |
| 61 | +6. If you receive feedback, make changes using your issue-specific branches of |
| 62 | + the forked repository and the pull requests will update automatically. |
| 63 | +7. Repeat as needed until all feedback has been addressed. |
| 64 | + |
| 65 | +When starting work, please make sure your clone of the originating `gh-pages` |
| 66 | +branch is up-to-date before creating your own revision-specific branch(es) from |
| 67 | +there. Additionally, please only work from your newly-created branch(es) and |
| 68 | +*not* your clone of the originating `gh-pages` branch. Lastly, published copies |
| 69 | +of all the lessons are available in the `gh-pages` branch of the originating |
| 70 | +repository for reference while revising. |
| 71 | + |
| 72 | +[github]: https://github.com |
| 73 | +[github-flow]: https://guides.github.com/introduction/flow/ |
| 74 | +[github-join]: https://github.com/join |
| 75 | +[how-contribute]: https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github |
| 76 | +[issues]: https://guides.github.com/features/issues/ |
0 commit comments