Skip to content

Commit 29396eb

Browse files
avantikalalavantikalal
authored
Merge pull request #103 from Genentech/docs
Updated contribution guide
2 parents ee5592d + 0f15ebe commit 29396eb

File tree

4 files changed

+121
-163
lines changed

4 files changed

+121
-163
lines changed

‎CONTRIBUTING.md‎

Lines changed: 120 additions & 150 deletions
Original file line numberDiff line numberDiff line change
@@ -1,193 +1,184 @@
11
# Contributing
22

3-
Welcome to ``gReLU`` contributor's guide.
3+
Welcome to the ``gReLU`` contributor's guide.
44

5-
This document focuses on getting any potential contributor familiarized
6-
with the development processes, but [other kinds of contributions](https://opensource.guide/how-to-contribute) are also
7-
appreciated.
5+
This document focuses on getting any potential contributor familiarized with the development processes,
6+
but [other kinds of contributions](https://opensource.guide/how-to-contribute) are also appreciated.
87

9-
If you are new to using git_ or have never collaborated in a project previously,
10-
please have a look at [contribution-guide.org](https://www.contribution-guide.org/). Other resources are also
11-
listed in the excellent [guide created by FreeCodeCamp](https://github.com/FreeCodeCamp/how-to-contribute) [#contrib1]_.
8+
If you are new to using git or have never collaborated in a project previously, please have a look at
9+
[contribution-guide.org](https://www.contribution-guide.org/). Other resources are also listed in the
10+
excellent [guide created by FreeCodeCamp](https://github.com/FreeCodeCamp/how-to-contribute).
1211

13-
Please notice, all users and contributors are expected to be **open,
14-
considerate, reasonable, and respectful**. When in doubt, [Python Software
15-
Foundation's Code of Conduct](https://www.python.org/psf/conduct/) is a good reference in terms of behavior
16-
guidelines.
12+
Please notice, all users and contributors are expected to be **open, considerate, reasonable, and
13+
respectful**. When in doubt, [Python Software Foundation's Code of Conduct](https://www.python.org/psf/conduct/)
14+
is a good reference in terms of behavior guidelines.
1715

1816
## Issue Reports
1917

20-
If you experience bugs or general issues with ``grelu``, please have a look
21-
on the [issue tracker](https://github.com/Genentech/gReLU/issues). If you don't see anything useful there, please feel
22-
free to fire an issue report.
18+
If you experience bugs or general issues with ``gReLU``, please have a look at the
19+
[issue tracker](https://github.com/Genentech/gReLU/issues). If you don't see anything useful there, please
20+
file a new issue report.
2321

24-
**Tip:** Please don't forget to include the closed issues in your search.
25-
Sometimes a solution was already reported, and the problem is considered
26-
**solved**.
22+
(Don't forget to include the closed issues in your search. Sometimes a solution was already reported, and
23+
the problem is considered solved.)
2724

28-
New issue reports should include information about your programming environment
29-
(e.g., operating system, Python version) and steps to reproduce the problem.
30-
Please try also to simplify the reproduction steps to a very minimal example
31-
that still illustrates the problem you are facing. By removing other factors,
32-
you help us to identify the root cause of the issue.
25+
You can file a new issue by clicking the "New issue" button at the top right of the issue tracker.
26+
![New Issue](media/new_issue.jpg)
3327

34-
## Documentation Improvements
28+
Your new issue report should include the following information:
3529

36-
You can help improve ``grelu`` docs by making them more readable and coherent, or
37-
by adding missing information and correcting mistakes.
30+
1. Information about your programming environment (e.g., operating system, Python version)
31+
2. Steps to reproduce the problem. Please try to simplify the reproduction steps to a very minimal example
32+
that still illustrates the problem you are facing. By removing other factors, you help us to identify the
33+
root cause of the issue.
34+
4. The full error message that you encountered, if any.
35+
5. Any steps that you took to diagnose or fix the issue, and their outcomes.
36+
6. Any suggestions for resolving the issue.
3837

39-
``grelu`` documentation uses [Sphinx](https://www.sphinx-doc.org/en/master/) as its main documentation compiler.
40-
This means that the docs are kept in the same repository as the project code, and
41-
that any documentation update is done in the same way was a code contribution.
4238

43-
**TODO:** Don't forget to mention which markup language you are using.
39+
## Making code contributions
4440

45-
e.g., reStructuredText_ or CommonMark_ with MyST_ extensions.
41+
### Coding resources
4642

47-
**TODO:** If your project is hosted on GitHub, you can also mention the following tip:
43+
``gReLU`` uses pytorch and pytorch-lightning. The below tutorials are good starting points to become familiar
44+
with these frameworks:
4845

49-
**Tip:** Please notice that the [GitHub web interface](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files) provides a quick way of
50-
propose changes in ``grelu``'s files. While this mechanism can
51-
be tricky for normal code contributions, it works perfectly fine for
52-
contributing to the docs, and can be quite handy.
46+
[PyTorch tutorials](https://pytorch.org/tutorials/beginner/basics/intro.html)
5347

54-
If you are interested in trying this method out, please navigate to
55-
the ``docs`` folder in the source repository_, find which file you
56-
would like to propose changes and click in the little pencil icon at the
57-
top, to open [GitHub's code editor](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files). Once you finish editing the file,
58-
please write a message in the form at the bottom of the page describing
59-
which changes have you made and what are the motivations behind them and
60-
submit your proposal.
48+
[Lightning tutorials](https://lightning.ai/docs/pytorch/stable/levels/core_skills.html)
6149

62-
When working on documentation changes in your local machine, you can
63-
compile them using `tox`::
50+
### Understanding project structure
6451

65-
tox -e docs
52+
We welcome external contributions to ``gReLU``. Before planning changes to the code, we suggest carefully
53+
examining the current structure and organization of the package.
54+
55+
The [API reference](https://genentech.github.io/gReLU/autoapi/index.html) lists all the modules and submodules
56+
available in gReLU. Clicking on individual modules on this list will reveal a description of the module and
57+
what kinds of functions it is meant to contain. The descriptions also contain more detailed explanations of the
58+
expected structure of each module and how to contribute to it. This will help you find the appropriate location
59+
to make changes.
6660

67-
and use Python's built-in web server for a preview in your web browser
68-
(``http://localhost:8000``)::
61+
For instance, the table below lists some different types of functionality that contributors may want to add
62+
or change, and the corresponding module / submodule of ``gReLU``. Click on the name of a module for more details
63+
on its structure.
6964

70-
python3 -m http.server --directory 'docs/_build/html'
65+
| Functionality | Module |
66+
| ---------------- | ------- |
67+
| Functions to read / write genomic data | [`grelu.io`](https://genentech.github.io/gReLU/autoapi/grelu/io/index.html) |
68+
| Functions to preprocess genomic data after it is loaded | [`grelu.data.preprocess`](https://genentech.github.io/gReLU/autoapi/grelu/data/preprocess/index.html) |
69+
| New augmentation functions for training models | [`grelu.data.augment`](https://genentech.github.io/gReLU/autoapi/grelu/data/augment/index.html) |
70+
| Functions to introduce various types of in silico mutations into DNA sequences | [`grelu.sequence.mutate`](https://genentech.github.io/gReLU/autoapi/grelu/sequence/mutate/index.html) |
71+
| Other functions to manipulate DNA sequences | [`grelu.sequence.utils`](https://genentech.github.io/gReLU/autoapi/grelu/sequence/utils/index.html) |
72+
| Functions to score DNA sequences based on their content | [`grelu.transforms.seq_transforms`](https://genentech.github.io/gReLU/autoapi/grelu/transforms/seq_transforms/index.html) |
73+
| Functions to transform model predictions | [`grelu.transforms.prediction_transforms`](https://genentech.github.io/gReLU/autoapi/grelu/transforms/prediction_transforms/index.html) |
74+
| New types of model layers | [`grelu.model.layers`](https://genentech.github.io/gReLU/autoapi/grelu/model/layers/index.html) |
75+
| New model architectures | [`grelu.model.models`](https://genentech.github.io/gReLU/autoapi/grelu/model/models/index.html) |
76+
| New loss functions | [`grelu.lightning.losses`](https://genentech.github.io/gReLU/autoapi/grelu/lightning/losses/index.html)|
77+
| New metrics to calculate model performance | [`grelu.lightning.metrics`](https://genentech.github.io/gReLU/autoapi/grelu/lightning/metrics/index.html) |
78+
| New plots and visualizations | [`grelu.visualize`](https://genentech.github.io/gReLU/autoapi/grelu/visualize/index.html) |
7179

72-
## Code Contributions
80+
For complex changes that may not fit clearly within the established package structure, it is important to first
81+
raise an issue (see instructions below).
7382

74-
**TODO:** Please include a reference or explanation about the internals of the project.
7583

76-
An architecture description, design principles or at least a summary of the
77-
main concepts will make it easy for potential contributors to get started
78-
quickly.
84+
## Step-by-step instructions to contribute new code
7985

80-
Submit an issue
81-
---------------
86+
### Submit an issue
8287

83-
Before you work on any non-trivial code contribution it's best to first create
84-
a report in the [issue tracker](https://github.com/Genentech/gReLU/issues) to start a discussion on the subject.
88+
Before you work on any non-trivial code contribution it's best to first create an issue in the
89+
[issue tracker](https://github.com/Genentech/gReLU/issues) to start a discussion on the subject.
8590
This often provides additional considerations and avoids unnecessary work.
8691

87-
Create an environment
88-
---------------------
92+
### Create an environment
8993

9094
Before you start coding, we recommend creating an isolated [virtual
91-
environment](https://realpython.com/python-virtual-environments-a-primer/) to avoid any problems with your installed Python packages.
92-
This can easily be done via either [virtualenv](https://virtualenv.pypa.io/en/stable/)::
93-
95+
environment](https://realpython.com/python-virtual-environments-a-primer/) to avoid any problems with your
96+
installed Python packages. This can easily be done via either [virtualenv](https://virtualenv.pypa.io/en/stable/):
97+
```
9498
virtualenv <PATH TO VENV>
9599
source <PATH TO VENV>/bin/activate
96-
97-
or [Miniconda](https://docs.conda.io/en/latest/miniconda.html)::
98-
100+
```
101+
or [Miniconda](https://docs.conda.io/en/latest/miniconda.html):
102+
```
99103
conda create -n grelu python=3 six virtualenv pytest pytest-cov
100104
conda activate grelu
105+
```
106+
### Clone the repository
101107

102-
Clone the repository
103-
--------------------
108+
1. Create an user account on [GitHub](https://github.com), if you do not already have one.
109+
2. Fork the [project repository](https://github.com/Genentech/gReLU/): click on the *Fork* button near the top of
110+
the page. This creates a copy of the code under your account on [GitHub](https://github.com/).
104111

105-
1. Create an user account on [the repository service](https://github.com). if you do not already have one.
106-
2. Fork the project repository_: click on the *Clone* button near the top of the
107-
page. This creates a copy of the code under your account on [the repository service](https://github.com/).
108-
3. Clone this copy to your local disk::
112+
![Fork](media/fork.jpg)
109113

114+
4. Clone this copy to your local disk::
115+
```
110116
git clone [email protected]:YourLogin/grelu.git
111117
cd grelu
112-
118+
```
113119
4. You should run::
114-
120+
```
115121
pip install -U pip setuptools -e .
116-
122+
```
117123
to be able to import the package under development in the Python REPL.
118124

119-
**TODO:** if you are not using pre-commit, please remove the following item:
120-
121-
5. Install [pre-commit](https://pre-commit.com/)::
122-
125+
5. Install [pre-commit](https://pre-commit.com/):
126+
```
123127
pip install pre-commit
124128
pre-commit install
125-
129+
```
126130
``grelu`` comes with a lot of hooks configured to automatically help the
127131
developer to check the code being written.
128132

129-
Implement your changes
130-
----------------------
133+
### Implement your changes
131134

132135
1. Create a branch to hold your changes::
133-
136+
```
134137
git checkout -b my-feature
135-
138+
```
136139
and start making changes. Never work on the main branch!
137140

138-
2. Start your work on this branch. Don't forget to add docstrings_ to new
139-
functions, modules and classes, especially if they are part of public APIs.
141+
2. Implement your code changes on this branch.
140142

141-
3. Add yourself to the list of contributors in ``AUTHORS.rst``.
143+
3. If you change or add any functions, modules and classes, don't forget to update or add docstrings to describe these changes.
142144

143-
4. When you’re done editing, do::
145+
4. If your contribution adds an additional feature and is not just a bugfix, we suggest also adding unit tests.
144146

147+
5. Add yourself to the list of contributors in ``AUTHORS.rst``.
148+
149+
6. When you’re done editing, do::
150+
```p
145151
git add <MODIFIED FILES>
146152
git commit
153+
```
154+
to record your changes in git. Moreover, writing a [descriptive commit message](https://chris.beams.io/posts/git-commit)
155+
is highly recommended.
147156

148-
to record your changes in git_.
149-
150-
**TODO:** if you are not using pre-commit, please remove the following item:
151-
152-
Please make sure to see the validation messages from [pre-commit](https://pre-commit.com/) and fix
153-
any eventual issues.
154-
This should automatically use [flake8](https://flake8.pycqa.org/en/stable/)/[black](https://pypi.org/project/black/) to check/fix the code style
155-
in a way that is compatible with the project.
156-
157-
**Important:** Don't forget to add unit tests and documentation in case your
158-
contribution adds an additional feature and is not just a bugfix.
159-
160-
Moreover, writing a [descriptive commit message](https://chris.beams.io/posts/git-commit) is highly recommended.
161-
In case of doubt, you can check the commit history with::
162-
163-
git log --graph --decorate --pretty=oneline --abbrev-commit --all
164-
165-
to look for recurring communication patterns.
157+
Please make sure to see the validation messages from [pre-commit](https://pre-commit.com/) and fix any issues.
158+
This should automatically use [flake8](https://flake8.pycqa.org/en/stable/)/[black](https://pypi.org/project/black/)
159+
to check/fix the code style in a way that is compatible with the project.
166160

167-
5. Please check that your changes don't break any unit tests with::
161+
### Test your changes
168162

163+
Please check that your changes don't break any unit tests with::
164+
```
169165
tox
170-
166+
```
171167
(after having installed [tox](https://tox.wiki/en/stable/) with ``pip install tox`` or ``pipx``).
172-
173168
You can also use [tox](https://tox.wiki/en/stable/) to run several other pre-configured tasks in the
174169
repository. Try ``tox -av`` to see a list of the available checks.
175170

176-
Submit your contribution
177-
------------------------
178-
179-
1. If everything works fine, push your local branch to [the repository service](https://github.com/) with::
171+
### Submit your contribution
180172

173+
1. If everything works fine, push your local branch to [GitHub](https://github.com/) with:
174+
```
181175
git push -u origin my-feature
182-
176+
```
183177
2. Go to the web page of your fork and click "Create pull request"
184178
to send your changes for review.
185179

186-
**TODO:** if you are using GitHub, you can uncomment the following paragraph
187-
188-
Find more detailed information in [creating a PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). You might also want to open
189-
the PR as a draft first and mark it as ready for review after the feedbacks
190-
from the continuous integration (CI) system or any required fixes.
180+
Find more detailed information in [creating a PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). You might also want to open the PR as a draft first and mark it as ready for review
181+
after the feedback from the continuous integration (CI) system or any required fixes.
191182

192183
## Troubleshooting
193184

@@ -206,13 +197,13 @@ package:
206197
``setup.cfg`` and ``docs/requirements.txt``. If you find any problems with
207198
missing dependencies when running a command with [tox](https://tox.wiki/en/stable/), try to recreate the
208199
``tox`` environment using the ``-r`` flag. For example, instead of::
209-
200+
```shell
210201
tox -e docs
211-
202+
```
212203
Try running::
213-
204+
```shell
214205
tox -r -e docs
215-
206+
```
216207
3. Make sure to have a reliable [tox](https://tox.wiki/en/stable/) installation that uses the correct
217208
Python version (e.g., 3.7+). When in doubt you can run::
218209

@@ -223,31 +214,25 @@ package:
223214
```
224215

225216
If you have trouble and are seeing weird errors upon running [tox](https://tox.wiki/en/stable/), you can
226-
also try to create a dedicated [virtual environment](https://realpython.com/python-virtual-environments-a-primer/) with a [tox](https://tox.wiki/en/stable/) binary
227-
freshly installed. For example::
217+
also try to create a dedicated [virtual environment](https://realpython.com/python-virtual-environments-a-primer/)
218+
with a [tox](https://tox.wiki/en/stable/) binary freshly installed. For example::
228219

229220
virtualenv .venv
230221
source .venv/bin/activate
231222
.venv/bin/pip install tox
232223
.venv/bin/tox -e all
233224

234-
4. [Pytest can drop you](https://docs.pytest.org/en/stable/how-to/failures.html#using-python-library-pdb-with-pytest) in an interactive session in the case an error occurs.
235-
In order to do that you need to pass a ``--pdb`` option (for example by
225+
4. [Pytest can drop you](https://docs.pytest.org/en/stable/how-to/failures.html#using-python-library-pdb-with-pytest) in an
226+
interactive session in the case an error occurs. In order to do that you need to pass a ``--pdb`` option (for example by
236227
running ``tox -- -k <NAME OF THE FALLING TEST> --pdb``).
237228
You can also setup breakpoints manually instead of using the ``--pdb`` option.
238229

239230
## Maintainer tasks
240231

241232
### Releases
242233

243-
**TODO:** This section assumes you are using PyPI to publicly release your package.
244-
245-
If instead you are using a different/private package index, please update
246-
the instructions accordingly.
247-
248-
If you are part of the group of maintainers and have correct user permissions
249-
on [PyPI](https://pypi.org/), the following steps can be used to release a new version for
250-
``grelu``:
234+
If you are part of the group of maintainers and have correct user permissions on [PyPI](https://pypi.org/),
235+
the following steps can be used to release a new version for ``grelu``:
251236

252237
1. Make sure all unit tests are successful.
253238
2. Tag the current commit on the main branch with a release tag, e.g., ``v1.2.3``.
@@ -256,23 +241,8 @@ on [PyPI](https://pypi.org/), the following steps can be used to release a new v
256241
(or ``rm -rf dist build``)
257242
to avoid confusion with old builds and Sphinx docs.
258243
5. Run ``tox -e build`` and check that the files in ``dist`` have
259-
the correct version (no ``.dirty`` or git_ hash) according to the git_ tag.
244+
the correct version (no ``.dirty`` or git hash) according to the git tag.
260245
Also check the sizes of the distributions, if they are too big (e.g., >
261246
500KB), unwanted clutter may have been accidentally included.
262247
6. Run ``tox -e publish -- --repository pypi`` and check that everything was
263248
uploaded to PyPI_ correctly.
264-
265-
.. [#contrib1] Even though, these resources focus on open source projects and
266-
communities, the general ideas behind collaborating with other developers
267-
to collectively create software are general and can be applied to all sorts
268-
of environments, including private companies and proprietary code bases.
269-
270-
.. <-- start -->
271-
**TODO:** Please review and change the following definitions:
272-
273-
.. |the repository service| replace:: GitLab
274-
.. |contribute button| replace:: "Create pull request"
275-
276-
.. _repository: https://github.com/Genentech/gReLU/
277-
.. _issue tracker: https://github.com/Genentech/gReLU/issues
278-
.. <-- end -->

0 commit comments

Comments
 (0)