A community-maintained Python framework for creating mathematical animations.
Rewrite contributing guide and add two troubleshooting soulutions (#384)
CorvidCanine95ff9f89d678
diff --git a/docs/source/contributing.md b/docs/source/contributing.mdindex 7e44f2461..2d7a4d11e 100644--- a/docs/source/contributing.md+++ b/docs/source/contributing.md@@ -4,71 +4,36 @@ Thank you for contributing to Manim! However you have decided to contribute orinteract with the community, please always be civil and respect other membersof the community. Manim is a free open source software for mathematicalanimations, and as such we welcome **everyone** who is interested in-mathematics, pedagogy, computer animations, open source, software development,+mathematics, pedagogy, computer animations, open-source, software development,and beyond. Manim accepts contributions of many kinds, detailed below.--## Reporting bugs--One of the best ways of contributing to Manim is by reporting bugs. If you-have encountered something that you believe is a bug, please follow these-steps:--1. First of all, make sure you are running the latest version of manim. If- not, update your version and try again.--2. Make sure to search for other users who may have had similar issues in the- past. Search the repository's issues page (don't forget to search closed- issues), bring it up on Discord, use sites like StackOverflow, and exercise- your best Google practices. If you can't find anything helpful, then go to- the next step.--3. Make sure you can reproduce the issue, i.e. that you have some code that- illustrates the bug **every time** (or at least most of the time) it is- executed.--4. Make sure to clarify what behavior you expected, and how the actual behavior- differs from your expectation.--5. Make sure to gather information about your environment, such as your- operating system, python version, and any stack traces that the code may- have generated (if applicable).--4. Please open an issue only after you have gathered this information. When- submitting an issue, make sure to follow the template (this is the default- text you are shown when first opening the 'New Issue' page). A community- member will (hopefully) respond and start a conversation to address the- issue.--7. Please give the community a reasonable amount of time before asking again,- or insisting on your issue. Keep in mind that everyone is a volunteer. If- you wait for a reasonable amount of time and you receive no response, feel- free to ask again.---## Contributing code-Many ways of contributing will involve writing, reading, testing, orrefactoring code. As our repository is a Fork of [Manim by3b1b](https://github.com/3b1b/manim), contributing in this way can be a bitconfusing. Here is a short guide on how to do it.-1. First, make a fork of this repository. This creates your own copy of the- whole codebase on GitHub.+1. 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 the repository you forked using the command below (bash/zsh).+2. Clone your fork.+ You can clone your Github fork by running:```shgit clone <your-fork-url>cd manim```- Note: do not `git clone` the original ManimCommunity repository. You must+ 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 mustclone your own fork. After this step, there are three differentrepositories to keep track of: the original ManimCommunity repo, your ownfork of it, and your local repository.-3. You have to make `git` be aware of the two remote repositories, by entering- the commands below.+3. Make `git` aware of the ManimCommunity repo.```shgit remote add upstream https://github.com/ManimCommunity/manim.git@@ -79,85 +44,118 @@ confusing. Here is a short guide on how to do it.(referred to as 'origin') as well as the main ManimCommunity repository(referred to as 'upstream').-4. Choose the correct branch for your changes. If you are working on a branch- that already exists on the main repository, you can execute+4. Choose the branch for your changes.++ To work on the ManimCommunity master branch, you can change to it with:```sh- git checkout -b <branch-name> upstream/master+ git checkout -b master upstream/master```If you are starting a new branch, execute```shgit checkout -b <new_branch-name>```+5. Install manim.++ Install the required packages and manim itself:+ ```sh+ pip install -e .+ ```++ Manim has other requirements that you will need to install,+ explained in the [Installation](installation) instructions.+- You can now make any changes to your local repository, add them, and commit+6. Write some awesome code!++ You're ready to make changes in your local repository, add them, and committhem.-5. To make your changes visible in your GitHub fork, instead of typing in `git- push` as usual, you need to enter the command below.+7. Update docstrings and documentation.- ```sh- git push -u origin <branch-name>- ```+ You should update the docstrings (the text in triple quotation marks) of any functions+ or 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.++ You must check that the command `make doctest`, executed from the `docs/` folder+ terminates without problems after your changes.++8. Add/update tests.++ 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.- Doing so creates a new branch with the updated contents of your fork on- GitHub (the 'origin').+9. Check for merge conflicts.-6. If you want your changes to be incorporated to the main ManimCommunity+ If you want your changes to be incorporated to the main ManimCommunityrepository, you need to make sure that there are no merge conflicts between- the current upstream/master and the changes you are trying to make. For- this purpose, please execute `git pull upstream master` before you push- changes to your fork. If this generates merge conflicts, make sure to- resolve them before submitting a PR.+ 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.-7. Further, make sure that you run the tests locally and that they all pass- before submitting a PR. You can run the tests locally by executing `pytest`- from the main `manim/` folder (do not execute pytest from the code folder- `manim/manim`).+10. Run the `black` autoformatter.-8. Finally, make sure to use the `black` autoformatter before submitting a PR.- You can execute it by running `black <your_file>`. This will make changes- to your code, and you will need to add/commit those changes.+ 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.-9. 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 picture below.+11. Run `pytest`.- + 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).- Once again, please make sure to follow the template (this is the default+12. 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.++ ```sh+ git push -u origin <branch-name>+ ```++ Doing so creates a new branch with the updated contents of your fork on+ GitHub (the 'origin').++13. Make a Pull Request on Github.++ 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 defaulttext you are shown when first opening the 'New Pull Request' page)-10. Once a PR is submitted, it will require at least two approving code- reviews from community developers, as well as all tests passing. It is- very likely that you will be asked to edit or modify your PR in one way or+14. Wait for feedback and make any requested changes.++ 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 oranother during this process. This is not an indictment of your work, butrather a strong signal that the dev community wants to merge your changes!-Note: before submitting a PR please make sure that you update the docstrings of-any methods, classes, or modules that your PR modifies, if necessary.--Note: if you are contributing new features or bug fixes, it is strongly-preferred that you include tests that accompany them in your PR. For this-purpose, you can create a new file under the `tests/` folder and make sure that-your new tests pass before submitting your PR. Please check out the [Wiki Entry-for Testing](https://github.com/ManimCommunity/manim/wiki/Testing) to learn-more about how our tests work.--Note: if you are contributing documentation, you must also make sure that the-command `make doctest`, executed from the `docs/` folder terminates without-problems. Please check out the [Wiki Entry for-Documentation](https://github.com/ManimCommunity/manim/wiki//Documentation-guidelines-(WIP))-to learn more about how we prefer our code documented.--Note: In order 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.+ 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.## Other guidelinesdiff --git a/docs/source/index.rst b/docs/source/index.rstindex cadc32677..8c4524b7b 100644--- a/docs/source/index.rst+++ b/docs/source/index.rst@@ -24,6 +24,7 @@ information here will make it easier for newcomers to get started usingreferenceexamplestutorials+ reporting_bugscontributingNavigationdiff --git a/docs/source/installation.rst b/docs/source/installation.rstindex cc407cad1..3195f6e0b 100644--- a/docs/source/installation.rst+++ b/docs/source/installation.rst@@ -51,6 +51,9 @@ cloned this repo, run the following:.. code-block:: bashpython3 -m pip install -r requirements.txt+ python3 -m pip install -e .++Please see :doc:`contributing` for more details about contributing to Manim... warning::If you want to contribute to ``manim-community`` and have cloned thediff --git a/docs/source/installation/troubleshooting.rst b/docs/source/installation/troubleshooting.rstindex 727c671a6..356008bac 100644--- a/docs/source/installation/troubleshooting.rst+++ b/docs/source/installation/troubleshooting.rst@@ -2,3 +2,13 @@ Troubleshooting===============List of known installation problems.++Some letters are missing from TextMobject/TexMobject output?+------------------------------------------------------------++If you have recently installed TeX you may need to build the fonts it+uses. Which can be done by running:++.. code-block:: bash++ fmtutil -sys --alldiff --git a/docs/source/reporting_bugs.rst b/docs/source/reporting_bugs.rstnew file mode 100644index 000000000..38db80a00--- /dev/null+++ b/docs/source/reporting_bugs.rst@@ -0,0 +1,37 @@+Reporting bugs+===============++One of the best ways of contributing to Manim is by reporting bugs. If you+have encountered something that you believe is a bug, please follow these+steps:++1. First of all, make sure you are running the latest version of manim. If+ not, update your version and try again.++2. Search for other users who may have had similar issues in the+ past. Search the repository's `issues page <https://github.com/ManimCommunity/manim/issues>`_ (don't forget to search closed+ issues), bring it up on out `Discord server <https://discord.gg/mMRrZQW>`_, use sites like StackOverflow, and exercise+ your best Google practices. If you can't find anything helpful, then go to+ the next step.++3. Can reproduce the issue, i.e. that you have some code that+ illustrates the bug **every time** (or at least most of the time) it is+ executed.++4. Clarify what behavior you expected, and how the actual behavior+ differs from your expectation.++5. Gather information about your environment, such as your+ operating system, python version, and any stack traces that the code may+ have generated (if applicable).++4. Please open an issue only after you have gathered this information. When+ submitting an issue, make sure to follow the template (this is the default+ text you are shown when first opening the 'New Issue' page). A community+ member will (hopefully) respond and start a conversation to address the+ issue.++7. Please give the community a reasonable amount of time before asking again,+ or insisting on your issue. Keep in mind that everyone is a volunteer. If+ you wait for a reasonable amount of time and you receive no response, feel+ free to ask again.