You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+53-94Lines changed: 53 additions & 94 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,114 +1,77 @@
1
-
# Contributing
1
+
# Contributing to ESMValTool tutorial
2
2
3
-
We greatly value contributions of any kind. Contributions could include fixes to this tutorial, bug reports, reviews of pull requests, infrastructure improvements, community help, and outreach. We value the time you invest in contributing and strive to make the process as easy as possible. If you have suggestions for improving the process of contributing, please do not hesitate to propose them.
3
+
[ESMValTool](https://www.esmvaltool.org/) tutorial is an open-source project and we greatly value contributions of all kinds: fixes to this tutorial, bug reports, reviews of pull requests, infrastructure improvements, community help, and outreach. We value the time you invest in contributing and strive to make the process as easy as possible. If you have suggestions for improving the process of contributing, please open an [issue][issues] by choosing the ``new feature`` template.
4
4
5
-
If you have a bug or other issue to report or just need help, please open an [issue].
5
+
## Acknowledgement
6
6
7
-
If you would like to contribute a new diagnostic and recipe or a new feature, please discuss your idea with the development team before getting started, to avoid double work and/or disappointment later. A good way to do this is to open an issue on GitHub. This is also a good way to get help.
7
+
The format of this tutorial is based on the [Software Carpentry][swc-site], which is an open-source project.
8
+
TODO escience academy
8
9
9
-
The format of this tutorial is based on the [Software Carpentry][swc-site], which is an open source project. We welcome contributions of all kinds:
10
-
fixes to this tutorial, bug reports, and reviews of proposed changes.
10
+
## Agreement
11
11
12
-
## Contributor Agreement
13
-
14
-
By contributing,
15
-
you agree that we may redistribute your work under [our license](LICENSE.md).
16
-
In exchange,
17
-
we will address your issues and/or assess your change proposal as promptly as we can,
18
-
and help you become a member of our community.
19
-
Everyone involved in [The Carpentries][c-site]
20
-
agrees to abide by our [code of conduct](CODE_OF_CONDUCT.md).
12
+
By contributing, you agree that we may redistribute your work under [our license](LICENSE.md).
13
+
In exchange, we will address your issues and/or assess your change proposal as promptly as we can, and help you become a member of our community.
14
+
Everyone involved in this [tutorial](site) agrees to abide by our [code of conduct](CODE_OF_CONDUCT.md).
21
15
22
16
## How to Contribute
23
17
24
-
The easiest way to get started is to file an issue
25
-
to tell us about a spelling mistake,
26
-
some awkward wording,
27
-
or a factual error.
28
-
This is a good way to introduce yourself
29
-
and to meet some of our community members.
18
+
There are many ways to contribute:
30
19
31
-
1. If you do not have a [GitHub][github] account,
32
-
you can [send us comments by email][email].
33
-
However,
34
-
we will be able to respond more quickly if you use one of the other methods described below.
20
+
If you wish to change this tutorial,
21
+
please work in <https://github.com/esmvalgroup/tutorial>,
22
+
which can be viewed at <https://esmvalgroup.github.io/tutorial>.
23
+
There are many ways to contribute,
24
+
from writing new exercises and improving existing ones
25
+
to updating or filling in the documentation
26
+
and submitting [bug reports][issues]
27
+
about things that don't work, aren't clear, or are missing.
28
+
If you are looking for ideas, please see the 'Issues' tab for
29
+
a list of issues associated with this repository,
35
30
36
-
2. If you have a [GitHub][github] account,
37
-
or are willing to [create one][github-join],
38
-
but do not know how to use Git,
39
-
you can report problems or suggest improvements by [creating an issue][issues].
40
-
This allows us to assign the item to someone
41
-
and to respond to it in a threaded discussion.
42
31
43
-
3. If you are comfortable with Git,
44
-
and would like to add or change material,
45
-
you can submit a pull request (PR).
46
-
Instructions for doing this are [included below](#using-github).
47
32
48
-
## Where to Contribute
33
+
* If you do not have a [GitHub][github] account,
34
+
you can [send us comments by email][email].
35
+
However,
36
+
we will be able to respond more quickly if you use one of the other methods described below.
49
37
50
-
1. If you wish to change this tutorial,
51
-
please work in <https://github.com/esmvalgroup/tutorial>,
52
-
which can be viewed at <https://esmvalgroup.github.io/tutorial>.
38
+
* If you have a [GitHub][github] account,
39
+
or are willing to [create one][github-join],
40
+
you can report problems or suggest improvements by [creating an issue][issues].
41
+
This is the easiest way to tell us about your ideas,
42
+
and a good way to introduce yourself
43
+
and to meet some of our community members.
44
+
This allows us to assign the item to someone
45
+
and to respond to it in a threaded discussion.
46
+
There are three templates to make an issue:
47
+
* for reporting a bug, please use [bug reports][issues]
48
+
* for developing lesson material, please use [New lesson material][issues]
49
+
* for adding a feature to the repository, please use [New feature][issues]
53
50
54
-
2. If you wish to change the Carpentries example lesson,
55
-
please work in <https://github.com/carpentries/lesson-example>,
56
-
which documents the format of the Carpentry lessons
57
-
and can be viewed at <https://carpentries.github.io/lesson-example>.
51
+
* If you would like to add what is already discussed in an issue,
52
+
you can submit a [pull request][PR].
53
+
To do so, you can make use of the [pull request checklist][PR].
54
+
The reviewers are community volunteers to provide feedback.
55
+
The maintainers have final say over what gets merged into the tutorial.
58
56
59
-
3. If you wish to change the template used for Carpentry workshop websites,
60
-
please work in <https://github.com/carpentries/workshop-template>.
61
-
The home page of that repository explains how to set up Carpentry workshop websites,
62
-
while the extra pages in <https://carpentries.github.io/workshop-template>
63
-
provide more background on our design choices.
57
+
## Lesson development guides
64
58
65
-
4. If you wish to change CSS style files, tools,
66
-
or HTML boilerplate for lessons or workshops stored in `_includes` or `_layouts`,
67
-
please work in <https://github.com/carpentries/styles>.
59
+
### Lesson development
60
+
61
+
### Lesson organization
62
+
63
+
### Lesson formatting
64
+
65
+
### Preview your changes locally
68
66
69
-
## What to Contribute
70
67
71
-
There are many ways to contribute,
72
-
from writing new exercises and improving existing ones
73
-
to updating or filling in the documentation
74
-
and submitting [bug reports][issues]
75
-
about things that don't work, aren't clear, or are missing.
76
-
If you are looking for ideas, please see the 'Issues' tab for
77
-
a list of issues associated with this repository,
78
-
or you may also look at the issues for [Data Carpentry][dc-issues],
79
-
[Software Carpentry][swc-issues], and [Library Carpentry][lc-issues] projects.
80
-
81
-
Comments on issues and reviews of pull requests are just as welcome:
82
-
we are smarter together than we are on our own.
83
-
Reviews from novices and newcomers are particularly valuable:
84
-
it's easy for people who have been using these lessons for a while
85
-
to forget how impenetrable some of this material can be,
86
-
so fresh eyes are always welcome.
87
-
88
-
## What *Not* to Contribute
89
-
90
-
Our lessons already contain more material than we can cover in a typical workshop,
91
-
so we are usually *not* looking for more concepts or tools to add to them.
92
-
As a rule,
93
-
if you want to introduce a new idea,
94
-
you must (a) estimate how long it will take to teach
95
-
and (b) explain what you would take out to make room for it.
96
-
The first encourages contributors to be honest about requirements;
97
-
the second, to think hard about priorities.
98
-
99
-
We are also not looking for exercises or other material that only run on one platform.
100
-
Our workshops typically contain a mixture of Windows, macOS, and Linux users;
101
-
in order to be usable,
102
-
our lessons must run equally well on all three.
103
68
104
69
## Using GitHub
105
70
106
71
If you choose to contribute via GitHub, you may want to look at
107
72
[How to Contribute to an Open Source Project on GitHub][how-contribute].
108
73
To manage changes, we follow [GitHub flow][github-flow].
109
-
Each lesson has two maintainers who review issues and pull requests or encourage others to do so.
110
-
The maintainers are community volunteers and have final say over what gets merged into the lesson.
111
-
To use the web interface for contributing to a lesson:
74
+
112
75
113
76
1. Fork the originating repository to your GitHub profile.
114
77
2. Within your version of the forked repository, move to the `gh-pages` branch and
@@ -117,9 +80,7 @@ create a new branch for each significant change being made.
117
80
4. Commit all changed files within the appropriate branches.
118
81
5. Create individual pull requests from each of your changed branches
119
82
to the `gh-pages` branch within the originating repository.
120
-
6. If you receive feedback, make changes using your issue-specific branches of the forked
121
-
repository and the pull requests will update automatically.
122
-
7. Repeat as needed until all feedback has been addressed.
83
+
123
84
124
85
When starting work, please make sure your clone of the originating `gh-pages` branch is up-to-date
125
86
before creating your own revision-specific branch(es) from there.
@@ -167,15 +128,13 @@ which everyone is welcome to join.
0 commit comments