|
1 | | -# Contributing New Material |
2 | | - |
3 | | -Data Carpentry is an open source project, and we welcome contributions of all |
4 | | -kinds: new and improved lessons, bug reports, and small fixes to existing |
5 | | -material are all useful. |
6 | | - |
7 | | -By contributing, you are agreeing that Data Carpentry may redistribute your |
8 | | -work under [these licenses](LICENSE.md). |
9 | | - |
10 | | - |
11 | | -**Table of Contents** |
12 | | - |
13 | | -- [Working With GitHub](#working-with-github) |
14 | | -- [Locations and Formats](#locations-and-formats) |
15 | | -- [Formatting of the material](#formatting-of-the-material) |
16 | | -- [Suggestions for Instructor Checkout](#suggestions-for-instructor-checkout) |
17 | | -- [FAQ](#faq) |
18 | | - |
19 | | - |
20 | | -## Working With GitHub |
21 | | - |
22 | | -1. Fork the `datacarpentry/lesson-name` repository on GitHub. |
23 | | - |
24 | | -2. The default branch in our lessons is `gh-pages`. Create a |
25 | | - new branch for your changes. |
26 | | - Give your branch a meaningful name, |
27 | | - such as `fixing-typos-in-shell-lesson` |
28 | | - or `adding-tutorial-on-visualization`. |
29 | | - |
30 | | -3. Clone this repository and branch to work with it on your computer. |
31 | | - git clone the repository with -b 'branch name' |
32 | | - |
33 | | -4. Make your changes, commit them, and push them to your repository on GitHub. |
34 | | - |
35 | | -5. Send a pull request to the `gh-pages` branch of the main datacarpentry |
36 | | - repository at http://github.com/datacarpentry/lesson-name. This can |
37 | | - be done through the github web interface. |
38 | | - |
39 | | -If it is easier for you to send them to us some other way, |
40 | | -please mail us at |
41 | | -[admin@datacarpentry.org](mailto:admin@datacarpentry.org). |
42 | | -Given a choice between you creating content or wrestling with Git, |
43 | | -we'd rather have you doing the former. |
44 | | - |
45 | | - |
46 | | -## Locations and Formats |
47 | | - |
48 | | -Every lesson has a repository of its own, while individual topics are files |
49 | | -in that directory. For example, the `python-ecology-lesson` repo containing our |
50 | | -introduction to Python using ecology data contains an `_episodes` folder, which |
51 | | -contains the files: `00-short-introduction-to-Python.md`, |
52 | | -`01-starting-with-data.md` and so on. (We use two digits followed by a short |
53 | | -topic key to ensure files appear in the right order when listed.) |
54 | | - |
55 | | -Lessons may be written in Markdown, as Jupyter Notebooks, or in other formats. |
56 | | -However, as explained in [the README file](README.md), Jekyll (the tool GitHub |
57 | | -uses to create websites) only knows how to handle Markdown and HTML. If some |
58 | | -other format is used, the author of the lesson must add the generated Markdown |
59 | | -to the repository. This ensures that people who *aren't* familiar with some |
60 | | -format don't have to install the tools needed to work with it (e.g., R |
61 | | -programmers don't have to install the Jupyter Notebook). |
62 | | - |
63 | | - |
64 | | -## Formatting of the material |
65 | | - |
66 | | -To ensure a consistent formatting of the lessons, we recommend the following |
67 | | -guidelines: |
68 | | - |
69 | | -- No trailing white space |
70 | | -- Wrap lines at 80 characters (unless it breaks URLs) |
71 | | -- Use unclosed [atx-style headers](http://spec.commonmark.org/0.25/#atx-headings) |
72 | | -- For Python code adhere to Style Guide defined in [PEP 8](https://www.python.org/dev/peps/pep-0008/) |
73 | | - |
74 | | - |
75 | | -## Suggestions for Instructor Checkout |
76 | | - |
77 | | -- [ ] Check links on setup [and install webpage](http://www.datacarpentry.org/python-ecology-lesson/). |
78 | | -- [ ] Check for presence of all "required" folders and csvs. We did some |
79 | | - remodeling, and there might be references that need scrubbing. |
80 | | -- [ ] Attendees have asked for a little more data manipulation and sorting. |
81 | | -- [ ] The plotting lesson could really use some love, and a discussion of |
82 | | - exporting high-quality plots. |
83 | | -- [ ] Lesson 7 repeats some matplot content, but with a new dataset. Rework to |
84 | | - use the previous lesson data. |
85 | | -- [x] The column name `plot_id` in surveys.csv confused a few participants who |
86 | | - didn't think of the word `plot_id` in terms of land, but in terms of a |
87 | | - drawing. Consider a rename to `site_id`. |
88 | | -- [ ] The 'short introduction to python' lesson overlaps quite a bit with the |
89 | | - 'data types and format' lesson when it comes to datatypes. Look over and |
90 | | - eliminate overlap. |
91 | | -- [ ] Read over challenges for precision, and check that the answers in the |
92 | | - (brand-new!) instructor guide make sense. |
93 | | - |
94 | | - |
95 | | -## FAQ |
96 | | - |
97 | | -- *Where can I get help?* |
98 | | - <br/> |
99 | | - Mail us at [admin@datacarpentry.org](mailto:admin@datacarpentry.org) |
100 | | - |
| 1 | +# Contributing |
| 2 | + |
| 3 | +[The Carpentries][c-site] ([Software Carpentry][swc-site], [Data Carpentry][dc-site], and [Library Carpentry][lc-site]) are open source projects, |
| 4 | +and we welcome contributions of all kinds: |
| 5 | +new lessons, |
| 6 | +fixes to existing material, |
| 7 | +bug reports, |
| 8 | +and reviews of proposed changes are all welcome. |
| 9 | + |
| 10 | +## Contributor Agreement |
| 11 | + |
| 12 | +By contributing, |
| 13 | +you agree that we may redistribute your work under [our license](LICENSE.md). |
| 14 | +In exchange, |
| 15 | +we will address your issues and/or assess your change proposal as promptly as we can, |
| 16 | +and help you become a member of our community. |
| 17 | +Everyone involved in [The Carpentries][c-site] |
| 18 | +agrees to abide by our [code of conduct](CODE_OF_CONDUCT.md). |
| 19 | + |
| 20 | +## How to Contribute |
| 21 | + |
| 22 | +The easiest way to get started is to file an issue |
| 23 | +to tell us about a spelling mistake, |
| 24 | +some awkward wording, |
| 25 | +or a factual error. |
| 26 | +This is a good way to introduce yourself |
| 27 | +and to meet some of our community members. |
| 28 | + |
| 29 | +1. If you do not have a [GitHub][github] account, |
| 30 | + you can [send us comments by email][email]. |
| 31 | + However, |
| 32 | + we will be able to respond more quickly if you use one of the other methods described below. |
| 33 | + |
| 34 | +2. If you have a [GitHub][github] account, |
| 35 | + or are willing to [create one][github-join], |
| 36 | + but do not know how to use Git, |
| 37 | + you can report problems or suggest improvements by [creating an issue][issues]. |
| 38 | + This allows us to assign the item to someone |
| 39 | + and to respond to it in a threaded discussion. |
| 40 | + |
| 41 | +3. If you are comfortable with Git, |
| 42 | + and would like to add or change material, |
| 43 | + you can submit a pull request (PR). |
| 44 | + Instructions for doing this are [included below](#using-github). |
| 45 | + |
| 46 | +## Where to Contribute |
| 47 | + |
| 48 | +1. If you wish to change this lesson, |
| 49 | + please work in <https://github.com/datacarpentry/python-ecology-lesson>, |
| 50 | + which can be viewed at <https://datacarpentry.github.io/python-ecology-lesson>. |
| 51 | + |
| 52 | +2. If you wish to change the example lesson, |
| 53 | + please work in <https://github.com/carpentries/lesson-example>, |
| 54 | + which documents the format of our lessons |
| 55 | + and can be viewed at <https://carpentries.github.io/lesson-example>. |
| 56 | + |
| 57 | +3. If you wish to change the template used for workshop websites, |
| 58 | + please work in <https://github.com/carpentries/workshop-template>. |
| 59 | + The home page of that repository explains how to set up workshop websites, |
| 60 | + while the extra pages in <https://carpentries.github.io/workshop-template> |
| 61 | + provide more background on our design choices. |
| 62 | + |
| 63 | +4. If you wish to change CSS style files, tools, |
| 64 | + or HTML boilerplate for lessons or workshops stored in `_includes` or `_layouts`, |
| 65 | + please work in <https://github.com/carpentries/styles>. |
| 66 | + |
| 67 | +## What to Contribute |
| 68 | + |
| 69 | +There are many ways to contribute, |
| 70 | +from writing new exercises and improving existing ones |
| 71 | +to updating or filling in the documentation |
| 72 | +and submitting [bug reports][issues] |
| 73 | +about things that don't work, aren't clear, or are missing. |
| 74 | +If you are looking for ideas, please see the 'Issues' tab for |
| 75 | +a list of issues associated with this repository, |
| 76 | +or you may also look at the issues for [Data Carpentry][dc-issues], |
| 77 | +[Software Carpentry][swc-issues], and [Library Carpentry][lc-issues] projects. |
| 78 | + |
| 79 | +Comments on issues and reviews of pull requests are just as welcome: |
| 80 | +we are smarter together than we are on our own. |
| 81 | +Reviews from novices and newcomers are particularly valuable: |
| 82 | +it's easy for people who have been using these lessons for a while |
| 83 | +to forget how impenetrable some of this material can be, |
| 84 | +so fresh eyes are always welcome. |
| 85 | + |
| 86 | +## What *Not* to Contribute |
| 87 | + |
| 88 | +Our lessons already contain more material than we can cover in a typical workshop, |
| 89 | +so we are usually *not* looking for more concepts or tools to add to them. |
| 90 | +As a rule, |
| 91 | +if you want to introduce a new idea, |
| 92 | +you must (a) estimate how long it will take to teach |
| 93 | +and (b) explain what you would take out to make room for it. |
| 94 | +The first encourages contributors to be honest about requirements; |
| 95 | +the second, to think hard about priorities. |
| 96 | + |
| 97 | +We are also not looking for exercises or other material that only run on one platform. |
| 98 | +Our workshops typically contain a mixture of Windows, macOS, and Linux users; |
| 99 | +in order to be usable, |
| 100 | +our lessons must run equally well on all three. |
| 101 | + |
| 102 | +## Using GitHub |
| 103 | + |
| 104 | +If you choose to contribute via GitHub, you may want to look at |
| 105 | +[How to Contribute to an Open Source Project on GitHub][how-contribute]. |
| 106 | +To manage changes, we follow [GitHub flow][github-flow]. |
| 107 | +Each lesson has two maintainers who review issues and pull requests or encourage others to do so. |
| 108 | +The maintainers are community volunteers and have final say over what gets merged into the lesson. |
| 109 | +To use the web interface for contributing to a lesson: |
| 110 | + |
| 111 | +1. Fork the originating repository to your GitHub profile. |
| 112 | +2. Within your version of the forked repository, move to the `gh-pages` branch and |
| 113 | +create a new branch for each significant change being made. |
| 114 | +3. Navigate to the file(s) you wish to change within the new branches and make revisions as required. |
| 115 | +4. Commit all changed files within the appropriate branches. |
| 116 | +5. Create individual pull requests from each of your changed branches |
| 117 | +to the `gh-pages` branch within the originating repository. |
| 118 | +6. If you receive feedback, make changes using your issue-specific branches of the forked |
| 119 | +repository and the pull requests will update automatically. |
| 120 | +7. Repeat as needed until all feedback has been addressed. |
| 121 | + |
| 122 | +When starting work, please make sure your clone of the originating `gh-pages` branch is up-to-date |
| 123 | +before creating your own revision-specific branch(es) from there. |
| 124 | +Additionally, please only work from your newly-created branch(es) and *not* |
| 125 | +your clone of the originating `gh-pages` branch. |
| 126 | +Lastly, published copies of all the lessons are available in the `gh-pages` branch of the originating |
| 127 | +repository for reference while revising. |
| 128 | + |
| 129 | +## Other Resources |
| 130 | + |
| 131 | +General discussion of [Software Carpentry][swc-site] and [Data Carpentry][dc-site] |
| 132 | +happens on the [discussion mailing list][discuss-list], |
| 133 | +which everyone is welcome to join. |
| 134 | +You can also [reach us by email][email]. |
| 135 | + |
| 136 | +[email]: mailto:admin@software-carpentry.org |
| 137 | +[dc-issues]: https://github.com/issues?q=user%3Adatacarpentry |
| 138 | +[dc-lessons]: http://datacarpentry.org/lessons/ |
| 139 | +[dc-site]: http://datacarpentry.org/ |
| 140 | +[discuss-list]: http://lists.software-carpentry.org/listinfo/discuss |
| 141 | +[github]: https://github.com |
| 142 | +[github-flow]: https://guides.github.com/introduction/flow/ |
| 143 | +[github-join]: https://github.com/join |
| 144 | +[how-contribute]: https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github |
| 145 | +[issues]: https://guides.github.com/features/issues/ |
| 146 | +[swc-issues]: https://github.com/issues?q=user%3Aswcarpentry |
| 147 | +[swc-lessons]: https://software-carpentry.org/lessons/ |
| 148 | +[swc-site]: https://software-carpentry.org/ |
| 149 | +[c-site]: https://carpentries.org/ |
| 150 | +[lc-site]: https://librarycarpentry.org/ |
| 151 | +[lc-issues]: https://github.com/issues?q=user%3Alibrarycarpentry |
0 commit comments