Skip to content

Commit bc90639

Browse files
dafnidrakedafnidrake
authored
Merge pull request #413 from albhasan/update_contributing
Update CONTRIBUTING.md
2 parents 5f66793 + 3f8e445 commit bc90639

File tree

1 file changed

+116
-146
lines changed

1 file changed

+116
-146
lines changed

‎CONTRIBUTING.md

Lines changed: 116 additions & 146 deletions
Original file line numberDiff line numberDiff line change
@@ -1,151 +1,121 @@
1-
# Contributing
2-
3-
[Software Carpentry][swc-site] and [Data Carpentry][dc-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 [Software Carpentry][swc-site] and [Data Carpentry][dc-site]
18-
agrees to abide by our [code of conduct](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][contact].
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/swcarpentry/shell-novice>,
50-
which can be viewed at <https://swcarpentry.github.io/shell-novice>.
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,
75-
please see [the list of issues for this repository][issues],
76-
or the issues for [Data Carpentry][dc-issues]
77-
and [Software Carpentry][swc-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,
105-
you may want to look at
106-
[How to Contribute to an Open Source Project on GitHub][how-contribute].
107-
In brief:
108-
109-
1. The published copy of the lesson is in the `gh-pages` branch of the repository
110-
(so that GitHub will regenerate it automatically).
111-
Please create all branches from that,
112-
and merge the [master repository][repo]'s `gh-pages` branch into your `gh-pages` branch
113-
before starting work.
114-
Please do *not* work directly in your `gh-pages` branch,
115-
since that will make it difficult for you to work on other contributions.
116-
117-
2. We use [GitHub flow][github-flow] to manage changes:
118-
1. Create a new branch in your desktop copy of this repository for each significant change.
119-
2. Commit the change in that branch.
120-
3. Push that branch to your fork of this repository on GitHub.
121-
4. Submit a pull request from that branch to the [master repository][repo].
122-
5. If you receive feedback,
123-
make changes on your desktop and push to your branch on GitHub:
124-
the pull request will update automatically.
125-
126-
Each lesson has two maintainers who review issues and pull requests
127-
or encourage others to do so.
128-
The maintainers are community volunteers,
129-
and have final say over what gets merged into the lesson.
130-
131-
## Other Resources
132-
133-
General discussion of [Software Carpentry][swc-site] and [Data Carpentry][dc-site]
134-
happens on the [discussion mailing list][discuss-list],
135-
which everyone is welcome to join.
136-
You can also [reach us by email][contact].
137-
138-
[contact]: mailto:admin@software-carpentry.org
1+
## Contributing
2+
3+
[The Carpentries][cp-site] ([Software Carpentry][swc-site], [Data
4+
Carpentry][dc-site], and [Library Carpentry][lc-site]) are open source
5+
projects, 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 [The Carpentries][cp-site] agrees to abide by
15+
our [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][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][issues]. This allows us to
30+
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).
35+
36+
Note: if you want to build the website locally, please refer to [The Workbench
37+
documentation][template-doc].
38+
39+
### Where to Contribute
40+
41+
1. If you wish to change this lesson, add issues and pull requests here.
42+
2. If you wish to change the template used for workshop websites, please refer
43+
to [The Workbench documentation][template-doc].
44+
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], or the issues for [Data Carpentry][dc-issues], [Library
53+
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
64+
workshop, so we are usually *not* looking for more concepts or tools to add to
65+
them. As a rule, if you want to introduce a new idea, you must (a) estimate how
66+
long it will take to teach and (b) explain what you would take out to make room
67+
for it. The first encourages contributors to be honest about requirements; the
68+
second, to think hard about priorities.
69+
70+
We are also not looking for exercises or other material that only run on one
71+
platform. Our workshops typically contain a mixture of Windows, macOS, and
72+
Linux users; in order to be usable, our lessons must run equally well on all
73+
three.
74+
75+
### Using GitHub
76+
77+
If you choose to contribute via GitHub, you may want to look at [How to
78+
Contribute to an Open Source Project on GitHub][how-contribute]. In brief, we
79+
use [GitHub flow][github-flow] to manage changes:
80+
81+
1. Create a new branch in your desktop copy of this repository for each
82+
significant change.
83+
2. Commit the change in that branch.
84+
3. Push that branch to your fork of this repository on GitHub.
85+
4. Submit a pull request from that branch to the [upstream repository][repo].
86+
5. If you receive feedback, make changes on your desktop and push to your
87+
branch on GitHub: the pull request will update automatically.
88+
89+
NB: The published copy of the lesson is usually in the `main` branch.
90+
91+
Each lesson has a team of maintainers who review issues and pull requests or
92+
encourage others to do so. The maintainers are community volunteers, and have
93+
final say over what gets merged into the lesson.
94+
95+
### Other Resources
96+
97+
The Carpentries is a global organisation with volunteers and learners all over
98+
the world. We share values of inclusivity and a passion for sharing knowledge,
99+
teaching and learning. There are several ways to connect with The Carpentries
100+
community listed at <https://carpentries.org/connect/> including via social
101+
media, slack, newsletters, and email lists. You can also [reach us by
102+
email][contact].
103+
104+
[repo]: https://github.com/datacarpentry/r-raster-vector-geospatial
105+
[contact]: mailto:team@carpentries.org
106+
[cp-site]: https://carpentries.org/
139107
[dc-issues]: https://github.com/issues?q=user%3Adatacarpentry
140-
[dc-lessons]: http://datacarpentry.org/lessons/
141-
[dc-site]: http://datacarpentry.org/
142-
[discuss-list]: http://lists.software-carpentry.org/listinfo/discuss
143-
[github]: http://github.com
108+
[dc-lessons]: https://datacarpentry.org/lessons/
109+
[dc-site]: https://datacarpentry.org/
110+
[discuss-list]: https://lists.software-carpentry.org/listinfo/discuss
111+
[github]: https://github.com
144112
[github-flow]: https://guides.github.com/introduction/flow/
145113
[github-join]: https://github.com/join
146114
[how-contribute]: https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github
147-
[issues]: https://github.com/swcarpentry/shell-novice/issues/
148-
[repo]: https://github.com/swcarpentry/shell-novice/
115+
[issues]: https://carpentries.org/help-wanted-issues/
116+
[lc-issues]: https://github.com/issues?q=user%3ALibraryCarpentry
149117
[swc-issues]: https://github.com/issues?q=user%3Aswcarpentry
150-
[swc-lessons]: http://software-carpentry.org/lessons/
151-
[swc-site]: http://software-carpentry.org/
118+
[swc-lessons]: https://software-carpentry.org/lessons/
119+
[swc-site]: https://software-carpentry.org/
120+
[lc-site]: https://librarycarpentry.org/
121+
[template-doc]: https://carpentries.github.io/workbench/

0 commit comments

Comments
 (0)