A community-maintained Python framework for creating mathematical animations.
reformat contributing.rst as restructuredText, try to simplify
Benjamin Hackl0fcaeb94d90e
diff --git a/docs/source/contributing.rst b/docs/source/contributing.rstindex 2d7a4d11e..da2c4fe1b 100644--- a/docs/source/contributing.rst+++ b/docs/source/contributing.rst@@ -1,4 +1,6 @@-# Contributing+############+Contributing+############Thank you for contributing to Manim! However you have decided to contribute orinteract with the community, please always be civil and respect other members@@ -8,180 +10,207 @@ mathematics, pedagogy, computer animations, open-source, software development,and beyond. Manim accepts contributions of many kinds, detailed below.Many ways of contributing will involve writing, reading, testing, or-refactoring code. As our repository is a Fork of [Manim by-3b1b](https://github.com/3b1b/manim), contributing in this way can be a bit+refactoring code. As our repository is a Fork of `Manim by+3b1b <https://github.com/3b1b/manim>`_, contributing in this way can be a bitconfusing. Here is a short guide on how to do it.-1. Make a fork of this repository on Github.+Setup Manim with Version Control+================================++#. *Make a fork of this repository on Github.*You will need an account with Github. This will allow you to make pull requests (PR)to the ManimCommunity repo later on.-2. Clone your fork.-+#. *Clone your fork.*You can clone your Github fork by running:- ```sh- git clone <your-fork-url>- cd manim- ```- GitHub will provide both a SSH (`[email protected]:<your-username>/manim.git`) and- HTTPS (`https://github.com/<your-username>/manim.git`) URL for cloning the repo.++ .. code-block:: shell++ git clone <your-fork-url>+ cd manim++ GitHub will provide both a SSH (``[email protected]:<your-username>/manim.git``) and+ HTTPS (``https://github.com/<your-username>/manim.git``) URL for cloning the repo.You can use whichever one you are setup for.- Note: Do not `git clone` the original ManimCommunity repository. You must- clone your own fork. After this step, there are three different- repositories to keep track of: the original ManimCommunity repo, your own- fork of it, and your local repository.+ .. WARNING::++ Do not ``git clone`` the original ManimCommunity repository. You must+ clone your own fork. After this step, there are three different+ repositories to keep track of: the original ManimCommunity repo, your own+ fork of it, and your local repository.-3. Make `git` aware of the ManimCommunity repo.+#. Make ``git`` aware of the ManimCommunity repo.- ```sh- git remote add upstream https://github.com/ManimCommunity/manim.git- git fetch upstream- ```+ .. code-block:: shell- After these commands, your local repository can keep track of your fork- (referred to as 'origin') as well as the main ManimCommunity repository- (referred to as 'upstream').+ git remote add upstream https://github.com/ManimCommunity/manim.git+ git fetch upstream-4. Choose the branch for your changes.+ After these commands, your local repository can keep track of your fork+ (referred to as 'origin') as well as the main ManimCommunity repository+ (referred to as 'upstream').+#. *Install manim.*+ See the :doc:`installation instructions for developers <installation/for_dev>` for+ details.++You are now ready to work on manim!+++Changing manim's Source Code+============================++#. *Choose the branch for your changes.*To work on the ManimCommunity master branch, you can change to it with:- ```sh- git checkout -b master upstream/master- ```- If you are starting a new branch, execute- ```sh- git checkout -b <new_branch-name>- ```-5. Install manim.+ .. code-block:: shell- Install the required packages and manim itself:- ```sh- pip install -e .- ```+ git checkout -b master upstream/master- Manim has other requirements that you will need to install,- explained in the [Installation](installation) instructions.+ If you are starting a new branch, execute+ .. code-block:: shell-6. Write some awesome code!+ git checkout -b <new branch name>+#. *Write some awesome code!*You're ready to make changes in your local repository, add them, and committhem.-7. Update docstrings and documentation.-- You should update the docstrings (the text in triple quotation marks) of any functions+#. *Update docstrings and documentation.*+ Update the docstrings (the text in triple quotation marks) of any functionsor classes you change and include them with any new functions you add.- There is a [Wiki Entry for- Documentation](https://github.com/ManimCommunity/manim/wiki//Documentation-guidelines-(WIP))- with more information about how we prefer our code to be documented.+ There is a `Wiki Entry for+ Documentation <https://github.com/ManimCommunity/manim/wiki/Documentation-guidelines-(WIP)>`_+ with more information about how we prefer our code to be documented. The content+ of the docstrings will be rendered in the :doc:`reference manual <reference>`.- You must check that the command `make doctest`, executed from the `docs/` folder- terminates without problems after your changes.+#. *Add new or update existing tests.*+ Depending on the changes you are making you will need to update or add new tests.+ It is strongly preferred that you include tests with your PR. Details of our testing+ system are explained in the+ `corresponding Wiki Entry <https://github.com/ManimCommunity/manim/wiki/Testing>`_.-8. Add/update tests.+As far as development on your local machine goes, these are the main steps you+should follow.- Depending on the changes you are making you will need to update or add new tests.- If you have added a new feature or bug fix, it is strongly- preferred that you include tests with your PR.- Please check out the [Wiki Entry for Testing](https://github.com/ManimCommunity/manim/wiki/Testing)- to learn how our tests work.+Polishing your Changes and Submitting them for Review+=====================================================++As soon as you are ready to share your local changes with the community+so that they can be discussed, go through the following steps to open a+pull request.-9. Check for merge conflicts.+.. NOTE::- If you want your changes to be incorporated to the main ManimCommunity- repository, you need to make sure that there are no merge conflicts between- the current upstream/master and the changes you are trying to make. To do this- you will need to update your local repo with any changes that have- been made to the ManimCommunity repo while you've been working with- `git pull upstream master`.- This will probably generate merge conflicts that you will need to resolve.+ To open a pull request (PR), you do not need to have everything+ (code / documentation / tests) complete and ready to go. However, the more complete+ your PR is, the easier it will be for community developers to review it, and the+ quicker it will be merged. If you open a PR that is still under development+ and you want a quick overview or start some discussion about planned+ yet-to-be-implemented changes, please mark your PR as a draft.-10. Run the `black` autoformatter.+#. *Update your GitHub fork with local changes.*+ To make your changes visible in your GitHub fork, instead of typing in+ ``git push`` as usual, you need to enter the command below.- You can run black on a file or directory with `black <file_or_directory>` to- format your code to the same standard as the rest of ManimCommunity.- This will make changes to your code, so you will need to add/commit those changes- if you commit before running it. Most python IDE/text editors have packages for- running black after every save if you would like to keep formatting consistent while- you work.+ .. code-block:: shell-11. Run `pytest`.+ git push -u origin <branch name>- You can check that everything is still working properly after your modifications- with `pytest`. Make sure that you run the tests locally and that they all pass- before submitting a PR. `pytest` should be run from the main `manim/`- folder (Not the `manim/manim` subfolder).+ Doing so creates a new branch with the updated contents of your fork on+ GitHub (the 'origin').-12. Update your GitHub fork with local changes.+#. *Make a Pull Request on Github.*+ In order to make the ManimCommunity development team aware of your changes,+ you can make a Pull Request to the Manim Community repository from your fork.- To make your changes visible in your GitHub fork, instead of typing in `git- push` as usual, you need to enter the command below.+ .. WARNING::- ```sh- git push -u origin <branch-name>- ```+ Make sure to select ``ManimCommunity/manim`` instead of ``3b1b/manim``+ as the base repository!- Doing so creates a new branch with the updated contents of your fork on- GitHub (the 'origin').+ Choose the branch with your changes from your fork as the head+ repository - see the screenshot below.-13. Make a Pull Request on Github.+ .. image:: /_static/pull-requests.PNG+ :align: center- To request the ManimCommunity dev team to incorporate the changes in your- fork into the main repository, you can make a Pull Request to the Manim- Community repo from your fork. Make sure to select `ManimCommunity/manim`- instead of `3b1b/manim` as the `base repository` and your fork and branch as- `head repository` - see the screenshot below.+ Please make sure you follow the template (this is the default+ text you are shown when first opening the 'New Pull Request' page).- - Please make sure you follow the template (this is the default- text you are shown when first opening the 'New Pull Request' page)+Your changes are eligible to be merged, if+#. there are no merge conflicts,+#. and if the tests in our pipeline passes.-14. Wait for feedback and make any requested changes.+You can check for merge conflicts between the current upstream/master and+your branch by executing ``git pull upstream master`` locally. If this+generates any merge conflicts, you need to resolve them and push an+updated version of the branch to your fork of the repository.- Thank you for contributing! Once your PR is submitted, it will require at least- two approving code reviews from community developers. It will also be automatically- tested. These tests must all pass for the PR to be merged.- You will likely be asked to edit or modify your PR in one way or- another during this process. This is not an indictment of your work, but- rather a strong signal that the dev community wants to merge your changes!+Our pipeline consists of a series of different tests that ensure+that manim still works as intended and that the code you added+sticks to our coding conventions.- Note: To open a PR, you do not need to have everything- (documentation/tests) complete and ready to go. However, the more complete- your PR is, the easier it will be for community devs to review it, and the- quicker it will be merged. If you open a PR that is still under development- and you want a quick overview or start some discussion about planned- yet-to-be-implemented changes, please mark your PR as a draft.+- *Code style*: We use the code style imposed+ by `Black <https://black.readthedocs.io/en/stable/>`_. The pipeline+ makes sure that the (Python) files changed in your pull request+ also adhere to this code style. If this step of the pipeline fails,+ fix your code style by running ``black <file or directory>`` to+ automatically format your files.+- *Tests*: The pipeline runs manim's test suite on different operating systems+ (the latest versions of Ubuntu, MacOS, and Windows) for different versions of Python.+ The test suite consists of two different kinds of tests: integration tests+ and doctests. You can run them locally by executing ``poetry run pytest``+ and ``poetry run pytest --doctest-modules manim``, respectively, from the+ root directory of your cloned fork.-## Other guidelines+- *Documentation*: We also build a version of the documentation corresponding+ to your pull request. Make sure not to introduce any Sphinx errors, and have+ a look at the built HTML files to see whether the formatting of the documentation+ you added looks like you intended. You can build the documentation locally+ by running ``make html`` from the ``docs`` directory.-1. When submitting a PR, please make special note of whether your proposed+Finally, if the pipeline passes and you are satisfied with your changes: wait for+feedback and iterate over requested changes. You will likely be asked to edit or+modify your PR in one way or another during this process.+This is not an indictment of your work, but rather a strong signal that the+community wants to merge your changes! Overall, in order for your PR to be merged+at least two approving code reviews from core community developers are required.+++Further useful guideline+========================++#. When submitting a PR, please make special note of whether your proposedchanges will result in breaking changes.-2. When submitting a PR, make sure that your proposed changes are as general as+#. When submitting a PR, make sure that your proposed changes are as general aspossible, and ready to be taken advantage of by all of manim's users. Inparticular, leave out any machine-specific configurations, or any personalinformation it may contain.-3. If you are a maintainer, please label issues and PRs appropriately and+#. If you are a maintainer, please label issues and PRs appropriately andfrequently.-4. When opening a new issue, if there are old issues that are related, link+#. When opening a new issue, if there are old issues that are related, linkthem in your new issue (even if the old ones are closed).-5. When submitting a code review, it is highly recommended that you adhere to- [these general guidelines](https://conventionalcomments.org/). Similarly,+#. When submitting a code review, it is highly recommended that you adhere to+ `these general guidelines <https://conventionalcomments.org/>`_. Similarly,when crafting commit messages, it is highly recommended that you adhere to- [these guidelines](https://www.conventionalcommits.org/en/v1.0.0/).+ `these guidelines <https://www.conventionalcommits.org/en/v1.0.0/>`_.-6. If you find stale or inactive issues that seem to be irrelevant, please post+#. If you find stale or inactive issues that seem to be irrelevant, please posta comment saying 'This issue should be closed', and a community developerwill take a look.-7. Please do as much as possible to keep issues, PRs, and development in+#. Please do as much as possible to keep issues, PRs, and development ingeneral as tidy as possible.+++**Thank you for contributing!**\ No newline at end of file