Skip to content

Commit 0fcaeb9

Browse files
committed
reformat contributing.rst as restructuredText, try to simplify
1 parent fd9bfac commit 0fcaeb9

File tree

1 file changed

+143
-114
lines changed

1 file changed

+143
-114
lines changed

docs/source/contributing.rst

Lines changed: 143 additions & 114 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Contributing
1+
############
2+
Contributing
3+
############
24

35
Thank you for contributing to Manim! However you have decided to contribute or
46
interact with the community, please always be civil and respect other members
@@ -8,180 +10,207 @@ mathematics, pedagogy, computer animations, open-source, software development,
810
and beyond. Manim accepts contributions of many kinds, detailed below.
911

1012
Many ways of contributing will involve writing, reading, testing, or
11-
refactoring code. As our repository is a Fork of [Manim by
12-
3b1b](https://github.com/3b1b/manim), contributing in this way can be a bit
13+
refactoring code. As our repository is a Fork of `Manim by
14+
3b1b <https://github.com/3b1b/manim>`_, contributing in this way can be a bit
1315
confusing. Here is a short guide on how to do it.
1416

15-
1. Make a fork of this repository on Github.
1617

18+
Setup Manim with Version Control
19+
================================
20+
21+
#. *Make a fork of this repository on Github.*
1722
You will need an account with Github. This will allow you to make pull requests (PR)
1823
to the ManimCommunity repo later on.
1924

20-
2. Clone your fork.
21-
25+
#. *Clone your fork.*
2226
You can clone your Github fork by running:
23-
```sh
24-
git clone <your-fork-url>
25-
cd manim
26-
```
27-
GitHub will provide both a SSH (`[email protected]:<your-username>/manim.git`) and
28-
HTTPS (`https://github.com/<your-username>/manim.git`) URL for cloning the repo.
27+
28+
.. code-block:: shell
29+
30+
git clone <your-fork-url>
31+
cd manim
32+
33+
GitHub will provide both a SSH (``[email protected]:<your-username>/manim.git``) and
34+
HTTPS (``https://github.com/<your-username>/manim.git``) URL for cloning the repo.
2935
You can use whichever one you are setup for.
3036

31-
Note: Do not `git clone` the original ManimCommunity repository. You must
32-
clone your own fork. After this step, there are three different
33-
repositories to keep track of: the original ManimCommunity repo, your own
34-
fork of it, and your local repository.
37+
.. WARNING::
38+
39+
Do not ``git clone`` the original ManimCommunity repository. You must
40+
clone your own fork. After this step, there are three different
41+
repositories to keep track of: the original ManimCommunity repo, your own
42+
fork of it, and your local repository.
3543

36-
3. Make `git` aware of the ManimCommunity repo.
44+
#. Make ``git`` aware of the ManimCommunity repo.
3745

38-
```sh
39-
git remote add upstream https://github.com/ManimCommunity/manim.git
40-
git fetch upstream
41-
```
46+
.. code-block:: shell
4247
43-
After these commands, your local repository can keep track of your fork
44-
(referred to as 'origin') as well as the main ManimCommunity repository
45-
(referred to as 'upstream').
48+
git remote add upstream https://github.com/ManimCommunity/manim.git
49+
git fetch upstream
4650
47-
4. Choose the branch for your changes.
51+
After these commands, your local repository can keep track of your fork
52+
(referred to as 'origin') as well as the main ManimCommunity repository
53+
(referred to as 'upstream').
4854

55+
#. *Install manim.*
56+
See the :doc:`installation instructions for developers <installation/for_dev>` for
57+
details.
58+
59+
You are now ready to work on manim!
60+
61+
62+
Changing manim's Source Code
63+
============================
64+
65+
#. *Choose the branch for your changes.*
4966
To work on the ManimCommunity master branch, you can change to it with:
50-
```sh
51-
git checkout -b master upstream/master
52-
```
5367

54-
If you are starting a new branch, execute
55-
```sh
56-
git checkout -b <new_branch-name>
57-
```
58-
5. Install manim.
68+
.. code-block:: shell
5969
60-
Install the required packages and manim itself:
61-
```sh
62-
pip install -e .
63-
```
70+
git checkout -b master upstream/master
6471
65-
Manim has other requirements that you will need to install,
66-
explained in the [Installation](installation) instructions.
72+
If you are starting a new branch, execute
6773

74+
.. code-block:: shell
6875
69-
6. Write some awesome code!
76+
git checkout -b <new branch name>
7077
78+
#. *Write some awesome code!*
7179
You're ready to make changes in your local repository, add them, and commit
7280
them.
7381

74-
7. Update docstrings and documentation.
75-
76-
You should update the docstrings (the text in triple quotation marks) of any functions
82+
#. *Update docstrings and documentation.*
83+
Update the docstrings (the text in triple quotation marks) of any functions
7784
or classes you change and include them with any new functions you add.
78-
There is a [Wiki Entry for
79-
Documentation](https://github.com/ManimCommunity/manim/wiki//Documentation-guidelines-(WIP))
80-
with more information about how we prefer our code to be documented.
85+
There is a `Wiki Entry for
86+
Documentation <https://github.com/ManimCommunity/manim/wiki/Documentation-guidelines-(WIP)>`_
87+
with more information about how we prefer our code to be documented. The content
88+
of the docstrings will be rendered in the :doc:`reference manual <reference>`.
8189

82-
You must check that the command `make doctest`, executed from the `docs/` folder
83-
terminates without problems after your changes.
90+
#. *Add new or update existing tests.*
91+
Depending on the changes you are making you will need to update or add new tests.
92+
It is strongly preferred that you include tests with your PR. Details of our testing
93+
system are explained in the
94+
`corresponding Wiki Entry <https://github.com/ManimCommunity/manim/wiki/Testing>`_.
8495

85-
8. Add/update tests.
96+
As far as development on your local machine goes, these are the main steps you
97+
should follow.
8698

87-
Depending on the changes you are making you will need to update or add new tests.
88-
If you have added a new feature or bug fix, it is strongly
89-
preferred that you include tests with your PR.
90-
Please check out the [Wiki Entry for Testing](https://github.com/ManimCommunity/manim/wiki/Testing)
91-
to learn how our tests work.
99+
Polishing your Changes and Submitting them for Review
100+
=====================================================
101+
102+
As soon as you are ready to share your local changes with the community
103+
so that they can be discussed, go through the following steps to open a
104+
pull request.
92105

93-
9. Check for merge conflicts.
106+
.. NOTE::
94107

95-
If you want your changes to be incorporated to the main ManimCommunity
96-
repository, you need to make sure that there are no merge conflicts between
97-
the current upstream/master and the changes you are trying to make. To do this
98-
you will need to update your local repo with any changes that have
99-
been made to the ManimCommunity repo while you've been working with
100-
`git pull upstream master`.
101-
This will probably generate merge conflicts that you will need to resolve.
108+
To open a pull request (PR), you do not need to have everything
109+
(code / documentation / tests) complete and ready to go. However, the more complete
110+
your PR is, the easier it will be for community developers to review it, and the
111+
quicker it will be merged. If you open a PR that is still under development
112+
and you want a quick overview or start some discussion about planned
113+
yet-to-be-implemented changes, please mark your PR as a draft.
102114

103-
10. Run the `black` autoformatter.
115+
#. *Update your GitHub fork with local changes.*
116+
To make your changes visible in your GitHub fork, instead of typing in
117+
``git push`` as usual, you need to enter the command below.
104118

105-
You can run black on a file or directory with `black <file_or_directory>` to
106-
format your code to the same standard as the rest of ManimCommunity.
107-
This will make changes to your code, so you will need to add/commit those changes
108-
if you commit before running it. Most python IDE/text editors have packages for
109-
running black after every save if you would like to keep formatting consistent while
110-
you work.
119+
.. code-block:: shell
111120
112-
11. Run `pytest`.
121+
git push -u origin <branch name>
113122
114-
You can check that everything is still working properly after your modifications
115-
with `pytest`. Make sure that you run the tests locally and that they all pass
116-
before submitting a PR. `pytest` should be run from the main `manim/`
117-
folder (Not the `manim/manim` subfolder).
123+
Doing so creates a new branch with the updated contents of your fork on
124+
GitHub (the 'origin').
118125

119-
12. Update your GitHub fork with local changes.
126+
#. *Make a Pull Request on Github.*
127+
In order to make the ManimCommunity development team aware of your changes,
128+
you can make a Pull Request to the Manim Community repository from your fork.
120129

121-
To make your changes visible in your GitHub fork, instead of typing in `git
122-
push` as usual, you need to enter the command below.
130+
.. WARNING::
123131

124-
```sh
125-
git push -u origin <branch-name>
126-
```
132+
Make sure to select ``ManimCommunity/manim`` instead of ``3b1b/manim``
133+
as the base repository!
127134

128-
Doing so creates a new branch with the updated contents of your fork on
129-
GitHub (the 'origin').
135+
Choose the branch with your changes from your fork as the head
136+
repository - see the screenshot below.
130137

131-
13. Make a Pull Request on Github.
138+
.. image:: /_static/pull-requests.PNG
139+
:align: center
132140

133-
To request the ManimCommunity dev team to incorporate the changes in your
134-
fork into the main repository, you can make a Pull Request to the Manim
135-
Community repo from your fork. Make sure to select `ManimCommunity/manim`
136-
instead of `3b1b/manim` as the `base repository` and your fork and branch as
137-
`head repository` - see the screenshot below.
141+
Please make sure you follow the template (this is the default
142+
text you are shown when first opening the 'New Pull Request' page).
138143

139-
![pull-requests-example-manim-community](./_static/pull-requests.PNG)
140144

141-
Please make sure you follow the template (this is the default
142-
text you are shown when first opening the 'New Pull Request' page)
145+
Your changes are eligible to be merged, if
146+
#. there are no merge conflicts,
147+
#. and if the tests in our pipeline passes.
143148

144-
14. Wait for feedback and make any requested changes.
149+
You can check for merge conflicts between the current upstream/master and
150+
your branch by executing ``git pull upstream master`` locally. If this
151+
generates any merge conflicts, you need to resolve them and push an
152+
updated version of the branch to your fork of the repository.
145153

146-
Thank you for contributing! Once your PR is submitted, it will require at least
147-
two approving code reviews from community developers. It will also be automatically
148-
tested. These tests must all pass for the PR to be merged.
149-
You will likely be asked to edit or modify your PR in one way or
150-
another during this process. This is not an indictment of your work, but
151-
rather a strong signal that the dev community wants to merge your changes!
154+
Our pipeline consists of a series of different tests that ensure
155+
that manim still works as intended and that the code you added
156+
sticks to our coding conventions.
152157

153-
Note: To open a PR, you do not need to have everything
154-
(documentation/tests) complete and ready to go. However, the more complete
155-
your PR is, the easier it will be for community devs to review it, and the
156-
quicker it will be merged. If you open a PR that is still under development
157-
and you want a quick overview or start some discussion about planned
158-
yet-to-be-implemented changes, please mark your PR as a draft.
158+
- *Code style*: We use the code style imposed
159+
by `Black <https://black.readthedocs.io/en/stable/>`_. The pipeline
160+
makes sure that the (Python) files changed in your pull request
161+
also adhere to this code style. If this step of the pipeline fails,
162+
fix your code style by running ``black <file or directory>`` to
163+
automatically format your files.
159164

165+
- *Tests*: The pipeline runs manim's test suite on different operating systems
166+
(the latest versions of Ubuntu, MacOS, and Windows) for different versions of Python.
167+
The test suite consists of two different kinds of tests: integration tests
168+
and doctests. You can run them locally by executing ``poetry run pytest``
169+
and ``poetry run pytest --doctest-modules manim``, respectively, from the
170+
root directory of your cloned fork.
160171

161-
## Other guidelines
172+
- *Documentation*: We also build a version of the documentation corresponding
173+
to your pull request. Make sure not to introduce any Sphinx errors, and have
174+
a look at the built HTML files to see whether the formatting of the documentation
175+
you added looks like you intended. You can build the documentation locally
176+
by running ``make html`` from the ``docs`` directory.
162177

163-
1. When submitting a PR, please make special note of whether your proposed
178+
Finally, if the pipeline passes and you are satisfied with your changes: wait for
179+
feedback and iterate over requested changes. You will likely be asked to edit or
180+
modify your PR in one way or another during this process.
181+
This is not an indictment of your work, but rather a strong signal that the
182+
community wants to merge your changes! Overall, in order for your PR to be merged
183+
at least two approving code reviews from core community developers are required.
184+
185+
186+
Further useful guideline
187+
========================
188+
189+
#. When submitting a PR, please make special note of whether your proposed
164190
changes will result in breaking changes.
165191

166-
2. When submitting a PR, make sure that your proposed changes are as general as
192+
#. When submitting a PR, make sure that your proposed changes are as general as
167193
possible, and ready to be taken advantage of by all of manim's users. In
168194
particular, leave out any machine-specific configurations, or any personal
169195
information it may contain.
170196

171-
3. If you are a maintainer, please label issues and PRs appropriately and
197+
#. If you are a maintainer, please label issues and PRs appropriately and
172198
frequently.
173199

174-
4. When opening a new issue, if there are old issues that are related, link
200+
#. When opening a new issue, if there are old issues that are related, link
175201
them in your new issue (even if the old ones are closed).
176202

177-
5. When submitting a code review, it is highly recommended that you adhere to
178-
[these general guidelines](https://conventionalcomments.org/). Similarly,
203+
#. When submitting a code review, it is highly recommended that you adhere to
204+
`these general guidelines <https://conventionalcomments.org/>`_. Similarly,
179205
when crafting commit messages, it is highly recommended that you adhere to
180-
[these guidelines](https://www.conventionalcommits.org/en/v1.0.0/).
206+
`these guidelines <https://www.conventionalcommits.org/en/v1.0.0/>`_.
181207

182-
6. If you find stale or inactive issues that seem to be irrelevant, please post
208+
#. If you find stale or inactive issues that seem to be irrelevant, please post
183209
a comment saying 'This issue should be closed', and a community developer
184210
will take a look.
185211

186-
7. Please do as much as possible to keep issues, PRs, and development in
212+
#. Please do as much as possible to keep issues, PRs, and development in
187213
general as tidy as possible.
214+
215+
216+
**Thank you for contributing!**

0 commit comments

Comments
 (0)