|
| 1 | +# Contributing |
| 2 | + |
| 3 | +[RO-Crate](roc-site) and [The Carpentries][c-site] (who provide the lesson template) |
| 4 | +are open source projects, |
| 5 | +and we welcome contributions of all kinds: new lessons, fixes to |
| 6 | +existing material, bug reports, and reviews of proposed changes are all |
| 7 | +welcome. |
| 8 | + |
| 9 | +## Contributor Agreement |
| 10 | + |
| 11 | +By contributing, you agree that we may redistribute your work under [our |
| 12 | +license](LICENSE.md). In exchange, we will address your issues and/or assess |
| 13 | +your change proposal as promptly as we can, and help you become a member of our |
| 14 | +community. Everyone involved in [RO-Crate](roc-site) agrees to abide by our |
| 15 | +[code of conduct](CODE_OF_CONDUCT.md). |
| 16 | + |
| 17 | +## How to Contribute |
| 18 | + |
| 19 | +The easiest way to get started is to file an issue to tell us about a spelling |
| 20 | +mistake, some awkward wording, or a factual error. This is a good way to |
| 21 | +introduce yourself and to meet some of our community members. |
| 22 | + |
| 23 | +1. If you do not have a [GitHub][github] account, you can [send us comments by |
| 24 | + email][roc-contact]. However, we will be able to respond more quickly if you use |
| 25 | + one of the other methods described below. |
| 26 | + |
| 27 | +2. If you have a [GitHub][github] account, or are willing to [create |
| 28 | + one][github-join], but do not know how to use Git, you can report problems |
| 29 | + or suggest improvements by [creating an issue][repo-issues]. This allows us |
| 30 | + to assign the item to someone and to respond to it in a threaded discussion. |
| 31 | + |
| 32 | +3. If you are comfortable with Git, and would like to add or change material, |
| 33 | + you can submit a pull request (PR). Instructions for doing this are |
| 34 | + [included below](#using-github). For inspiration about changes that need to |
| 35 | + be made, check out the [list of open issues][issues] across the Carpentries. |
| 36 | + |
| 37 | +Note: if you want to build the website locally, please refer to [The Workbench |
| 38 | +documentation][template-doc]. |
| 39 | + |
| 40 | +## Where to Contribute |
| 41 | + |
| 42 | +1. If you wish to change this lesson, add issues and pull requests here. |
| 43 | +2. If you wish to change the template used for workshop websites, please refer |
| 44 | + to [The Workbench documentation][template-doc]. |
| 45 | + |
| 46 | +## What to Contribute |
| 47 | + |
| 48 | +There are many ways to contribute, from writing new exercises and improving |
| 49 | +existing ones to updating or filling in the documentation and submitting [bug |
| 50 | +reports][issues] about things that do not work, are not clear, or are missing. |
| 51 | +If you are looking for ideas, please see [the list of issues for this |
| 52 | +repository][repo-issues], or the issues for [Data Carpentry][dc-issues], |
| 53 | +[Library Carpentry][lc-issues], and [Software Carpentry][swc-issues] projects. |
| 54 | + |
| 55 | +Comments on issues and reviews of pull requests are just as welcome: we are |
| 56 | +smarter together than we are on our own. **Reviews from novices and newcomers |
| 57 | +are particularly valuable**: it's easy for people who have been using these |
| 58 | +lessons for a while to forget how impenetrable some of this material can be, so |
| 59 | +fresh eyes are always welcome. |
| 60 | + |
| 61 | +## What *Not* to Contribute |
| 62 | + |
| 63 | +Our lessons already contain more material than we can cover in a typical workshop, |
| 64 | +so we are usually *not* looking for more concepts or tools to add to them. |
| 65 | +As a rule, |
| 66 | +if you want to introduce a new idea, |
| 67 | +you must (a) estimate how long it will take to teach |
| 68 | +and (b) explain what you would take out to make room for it. |
| 69 | +The first encourages contributors to be honest about requirements; |
| 70 | +the second, to think hard about priorities. |
| 71 | + |
| 72 | +We are also not looking for exercises or other material that only run on one platform. |
| 73 | +Our workshops typically contain a mixture of Windows, macOS, and Linux users; |
| 74 | +in order to be usable, |
| 75 | +our lessons must run equally well on all three. |
| 76 | + |
| 77 | +## Using GitHub |
| 78 | + |
| 79 | +If you choose to contribute via GitHub, you may want to look at [How to |
| 80 | +Contribute to an Open Source Project on GitHub][how-contribute]. In brief, we |
| 81 | +use [GitHub flow][github-flow] to manage changes: |
| 82 | + |
| 83 | +1. Create a new branch in your desktop copy of this repository for each |
| 84 | + significant change. |
| 85 | +2. Commit the change in that branch. |
| 86 | +3. Push that branch to your fork of this repository on GitHub. |
| 87 | +4. Submit a pull request from that branch to the [upstream repository][repo]. |
| 88 | +5. If you receive feedback, make changes on your desktop and push to your |
| 89 | + branch on GitHub: the pull request will update automatically. |
| 90 | + |
| 91 | +NB: The published copy of the lesson is usually in the `main` branch. |
| 92 | + |
| 93 | +Each lesson has a team of maintainers who review issues and pull requests or |
| 94 | +encourage others to do so. The maintainers are community volunteers, and have |
| 95 | +final say over what gets merged into the lesson. |
| 96 | + |
| 97 | +## Other Resources |
| 98 | + |
| 99 | +General discussion of [RO-Crate][roc-site] happens on the |
| 100 | +[RO-Crate GitHub repository](https://github.com/ResearchObject/ro-crate) and in our |
| 101 | +[community spaces](https://www.researchobject.org/ro-crate/community), |
| 102 | +which everyone is welcome to join. |
| 103 | +You can also [reach us by email][roc-contact]. |
| 104 | + |
| 105 | +The Carpentries is a global organisation with volunteers and learners all over |
| 106 | +the world. We share values of inclusivity and a passion for sharing knowledge, |
| 107 | +teaching and learning. There are several ways to connect with The Carpentries |
| 108 | +community listed at <https://carpentries.org/connect/> including via social |
| 109 | +media, slack, newsletters, and email lists. You can also [reach us by |
| 110 | +email][cp-contact]. |
| 111 | + |
| 112 | + |
| 113 | +[roc-contact]: mailto:[email protected] |
| 114 | +[roc-site]: https://www.researchobject.org/ro-crate/ |
| 115 | +[repo]: https://github.com/ResearchObject/packaging_data_with_ro-crate |
| 116 | +[repo-issues]: https://github.com/ResearchObject/packaging_data_with_ro-crate/issues |
| 117 | +[cp-contact]: mailto:[email protected] |
| 118 | +[cp-site]: https://carpentries.org/ |
| 119 | +[dc-issues]: https://github.com/issues?q=user%3Adatacarpentry |
| 120 | +[dc-lessons]: https://datacarpentry.org/lessons/ |
| 121 | +[dc-site]: https://datacarpentry.org/ |
| 122 | +[discuss-list]: https://carpentries.topicbox.com/groups/discuss |
| 123 | +[github]: https://github.com |
| 124 | +[github-flow]: https://guides.github.com/introduction/flow/ |
| 125 | +[github-join]: https://github.com/join |
| 126 | +[how-contribute]: https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github |
| 127 | +[issues]: https://carpentries.org/help-wanted-issues/ |
| 128 | +[lc-issues]: https://github.com/issues?q=user%3ALibraryCarpentry |
| 129 | +[swc-issues]: https://github.com/issues?q=user%3Aswcarpentry |
| 130 | +[swc-lessons]: https://software-carpentry.org/lessons/ |
| 131 | +[swc-site]: https://software-carpentry.org/ |
| 132 | +[lc-site]: https://librarycarpentry.org/ |
| 133 | +[template-doc]: https://carpentries.github.io/workbench/ |
0 commit comments