1
- # Contributing
1
+ ############
2
+ Contributing
3
+ ############
2
4
3
5
Thank you for contributing to Manim! However you have decided to contribute or
4
6
interact with the community, please always be civil and respect other members
@@ -8,180 +10,207 @@ mathematics, pedagogy, computer animations, open-source, software development,
8
10
and beyond. Manim accepts contributions of many kinds, detailed below.
9
11
10
12
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
13
15
confusing. Here is a short guide on how to do it.
14
16
15
- 1. Make a fork of this repository on Github.
16
17
18
+ Setup Manim with Version Control
19
+ ================================
20
+
21
+ #. *Make a fork of this repository on Github. *
17
22
You will need an account with Github. This will allow you to make pull requests (PR)
18
23
to the ManimCommunity repo later on.
19
24
20
- 2. Clone your fork.
21
-
25
+ #. *Clone your fork. *
22
26
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.
29
35
You can use whichever one you are setup for.
30
36
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.
35
43
36
- 3 . Make `git ` aware of the ManimCommunity repo.
44
+ # . Make `` git ` ` aware of the ManimCommunity repo.
37
45
38
- ```sh
39
- git remote add upstream https://github.com/ManimCommunity/manim.git
40
- git fetch upstream
41
- ` ``
46
+ .. code-block :: shell
42
47
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
46
50
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').
48
54
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. *
49
66
To work on the ManimCommunity master branch, you can change to it with:
50
- ```sh
51
- git checkout -b master upstream/master
52
- ` ``
53
67
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
59
69
60
- Install the required packages and manim itself:
61
- ```sh
62
- pip install -e .
63
- ` ``
70
+ git checkout -b master upstream/master
64
71
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
67
73
74
+ .. code-block :: shell
68
75
69
- 6. Write some awesome code!
76
+ git checkout -b < new branch name >
70
77
78
+ #. *Write some awesome code! *
71
79
You're ready to make changes in your local repository, add them, and commit
72
80
them.
73
81
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
77
84
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 >`.
81
89
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 >`_.
84
95
85
- 8. Add/update tests.
96
+ As far as development on your local machine goes, these are the main steps you
97
+ should follow.
86
98
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.
92
105
93
- 9. Check for merge conflicts.
106
+ .. NOTE ::
94
107
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.
102
114
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.
104
118
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
111
120
112
- 11. Run ` pytest `.
121
+ git push -u origin < branch name >
113
122
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').
118
125
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.
120
129
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 ::
123
131
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!
127
134
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 .
130
137
131
- 13. Make a Pull Request on Github.
138
+ .. image :: /_static/pull-requests.PNG
139
+ :align: center
132
140
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).
138
143
139
- 
140
144
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.
143
148
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.
145
153
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.
152
157
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 .
159
164
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.
160
171
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.
162
177
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
164
190
changes will result in breaking changes.
165
191
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
167
193
possible, and ready to be taken advantage of by all of manim's users. In
168
194
particular, leave out any machine-specific configurations, or any personal
169
195
information it may contain.
170
196
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
172
198
frequently.
173
199
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
175
201
them in your new issue (even if the old ones are closed).
176
202
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,
179
205
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/ >`_ .
181
207
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
183
209
a comment saying 'This issue should be closed', and a community developer
184
210
will take a look.
185
211
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
187
213
general as tidy as possible.
214
+
215
+
216
+ **Thank you for contributing! **
0 commit comments