Skip to content

Commit d54d3f1

Browse files
arnodelormearnodelorme
authored
Create CONTRIBUTING.md
1 parent 03b92b0 commit d54d3f1

File tree

1 file changed

+184
-0
lines changed

1 file changed

+184
-0
lines changed

‎CONTRIBUTING.md

+184
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
# Contributing to EEGLAB
2+
3+
There are several ways in which you can contribute to the ongoing development of EEGLAB:
4+
5+
## Bug reporting
6+
7+
1. Please search on both the [EEGLAB discussion list archive](https://sccn.ucsd.edu/pipermail/eeglablist/)
8+
(to search the list Google "eeglablist your question")
9+
and the [GitHub issue list](https://github.com/sccn/eeglab/issues)
10+
to see if anybody else has lodged a similar observation.
11+
12+
3. How confident are you that the behavior you have observed is in fact a
13+
genuine bug, and not a misunderstanding?
14+
15+
- *Confident*: Please [open a new GitHub issue](https://github.com/sccn/eeglab/issues/new);
16+
select the "bug report" issue template to get started.
17+
18+
- *Not so confident*: That's fine! Consider instead creating a new topic
19+
on the [EEGLAB discussion list](https://eeglab.org/others/EEGLAB_mailing_lists.html);
20+
others can then comment on your observation and determine the
21+
appropriate level of escalation.
22+
23+
## Requesting a new feature
24+
25+
Please search the [GitHub issue list](https://github.com/sccn/eeglab/issues)
26+
to see if anybody else has made a comparable request:
27+
28+
- If a corresponding issue already exists, please add a comment to that
29+
issue to escalate the request. Additionally, describe any
30+
aspect of that feature not yet described in the existing issue.
31+
32+
- If no such listing exists, then you are welcome to create a [new
33+
issue](https://github.com/sccn/eeglab/issues/new) outlining the
34+
request. Be sure to select the "feature request" option to get started
35+
with writing the issue.
36+
37+
## Asking questions
38+
39+
General questions regarding EEGLAB download, usage, or any other
40+
aspect that is not specific to the EEGLAB *code*, should be directed to
41+
the [EEGLAB discussion list](https://eeglab.org/others/EEGLAB_mailing_lists.html). Also check
42+
the [online documentation](https://eeglab.org/).
43+
44+
## Making direct contributions
45+
46+
Thanks for your interest in making direct contributions to EEGLAB!
47+
We are excited to expand the breadth of researchers involved in improving
48+
and expanding this software, and to ensure that all who make such
49+
contributions receive appropriate acknowledgment through Git.
50+
51+
The instructions below give a short overview of how to go about generating a
52+
proposed change to EEGLAB. A more detailed tutorial on using Git and contributing
53+
to the code (or website) is presented as [online tutorial](https://eeglab.org/tutorials/contribute/)
54+
on the EEGLAB website.
55+
56+
1. You will need to create a *fork* of the [EEGLAB repository](https://github.com/sccn/eeglab)
57+
into your GitHub account, where unlike the main EEGLAB repository,
58+
you will have full write access to make the requisite changes.
59+
60+
2. Create a Git branch that is named appropriately according to the
61+
modifications that are being made. The existing code branch on which
62+
this new derived branch should be based depends on the nature of the
63+
proposed change (described later below).
64+
65+
3. Generate one or more Git commits that apply your proposed changes to
66+
the repository:
67+
68+
- Individual commits should ideally have a clear singular purpose,
69+
and not incorporate multiple unrelated changes. If your proposed
70+
changes involve multiple disparate components, consider breaking
71+
those changes up into individual commits.
72+
73+
Conversely, if multiple code changes are logically grouped with /
74+
linked to one another, these should ideally be integrated into a
75+
single commit.
76+
77+
- Commits should contain an appropriate message that adequately
78+
describes the change encapsulated within.
79+
80+
If the change demands a longer description, then the commit message
81+
should be broken into a synopsis (less than 80 characters) and message
82+
body, separated by two newline characters (as this enables GitHub to
83+
parse them appropriately).
84+
85+
This can be achieved at the command-line as follows:
86+
87+
`$ git commit -m $'Commit synopsis\n\nHere is a much longer and wordier description of my proposed changes that doesn\'t fit into 80 characters.\nI can even spread the message body across multiple lines.'`
88+
89+
(Note also the escape character "`\`" necessary for including an
90+
apostrophe in the message text)
91+
92+
- Where relevant, commit messages can also contain references to
93+
GitHub issues or pull requests (type the "`#`" character followed
94+
by the issue / PR number), and/or other individual commits (copy
95+
and paste the first 8-10 characters of the commit hash).
96+
97+
- If multiple persons have contributed to the proposed changes, it is
98+
possible to modify individual Git commits to have [multiple
99+
authors](https://help.github.com/en/articles/creating-a-commit-with-multiple-authors),
100+
to ensure that all contributors receive appropriate acknowledgement.
101+
102+
As a general rule: Git commits and commit messages should be constructed
103+
in such a way that, at some time in the future, when one is navigating
104+
through the contribution history, the evolution of the code is as clear
105+
as possible.
106+
107+
4. Identify the appropriate classification of the change that you propose
108+
to make, and read the relevant instructions there:
109+
110+
- "[**Fix**](#fix)": If the current code behaviour is
111+
*clearly incorrect*.
112+
113+
- "[**Enhancement**](#enhancement)": If the proposed change improves the *performance* or extends the *functionality* of a particular command or process.
114+
115+
- "[**Documentation**](#documentation)": If you made some changes to the function description in the help section of the function.
116+
117+
5. Check that your modified code does not prevent EEGLAB from
118+
passing existing tests, wherever possible (all test files are in the EEGLAB test directory).
119+
120+
6. For code contributions, if possible, a unit test or reproducibility
121+
test should be added. This not only demonstrates the behavior of the
122+
proposed code, but will also preclude future regression of the behavior
123+
of that code.
124+
125+
1. Once completed, a Pull Request should be generated that merges the
126+
corresponding branch in your forked version of the EEGLAB repository
127+
into the appropriate target branch of the main EEGLAB repository
128+
itself:
129+
130+
- If your intended changes are complete, and you consider them ready
131+
to be reviewed by an EEGLAB team member and merged imminently,
132+
then create a standard Pull Request.
133+
134+
- If your changes are ongoing, and you are seeking feedback from the
135+
EEGLAB developers before completing them, then also create a standard pull
136+
request. When you modify your code, the pull request will automatically
137+
be updated.
138+
139+
#### Fix
140+
141+
1. If there does not already exist a [GitHub issue](https://github.com/sccn/eeglab/issues)
142+
describing the bug, consider reporting the bug as a standalone issue
143+
prior to progressing further; that way developers can confirm the issue,
144+
and possibly provide guidance if you intend to resolve the issue yourself.
145+
Later, the Pull Request incorporating the necessary changes should then
146+
reference the listed issue (simply add somewhere in the description
147+
section the "`#`" character followed by the issue number).
148+
149+
2. Bug fixes are merged directly to `master`; as such, modifications to the
150+
code should be made in a branch that is derived from `master`, and the
151+
corresponding Pull Request should select `master` as the target branch
152+
for code merging.
153+
154+
3. A unit test or reproducibility test should ideally be added: such a
155+
test should fail when executed using the current `master` code, but pass
156+
when executed with the proposed changes.
157+
158+
#### Enhancement
159+
160+
1. New features, as well as any code changes that extend the functionality of
161+
EEGLAB, are merged to the `develop` branch, which contains
162+
all resolved changes since the most recent tag update. As such, any
163+
proposed changes that fall under this classification should be made
164+
in a branch that is based off of the `develop` branch, and the corresponding
165+
Pull Request should select `develop` as the target branch for code merging.
166+
167+
#### Documentation
168+
169+
If you want to contribute to the documentation on the EEGLAB website, please refer to the website's [Github repository](https://github.com/sccn/sccn.github.io).
170+
171+
#### Coding conventions
172+
173+
Please follow the [MATLAB style guidelines](https://www.mathworks.com/matlabcentral/fileexchange/46056-matlab-style-guidelines-2-0) for guidelines on contributing to the EEGLAB code base.
174+
175+
Non-exhaustive summary of coding guidelines:
176+
177+
* 2 space indents; indent using spaces and not tabs
178+
* No spaces between function name and opening parenthesis of argument list
179+
* One space after the comma that separates function arguments
180+
* Vertically align code with spaces in case it improves readability
181+
182+
#### References
183+
184+
This document is based on the excellent CONTRIBUTING.md document from the [MRTRIX repository](https://github.com/MRtrix3/mrtrix3/), and adjusted accordingly.

0 commit comments

Comments
 (0)