Skip to content

Rewrite contributing guide and add two troubleshooting soulutions #384

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Sep 5, 2020
Merged

Rewrite contributing guide and add two troubleshooting soulutions #384

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5ed8945
Move bug report guide to own page, rewrite contributing guide, add a …
CorvidCanine Sep 2, 2020
0d14c95
Apply suggestions from code review of contributing guide rewrite
CorvidCanine Sep 3, 2020
48ac811
Change contributing guide to checkout master
CorvidCanine Sep 3, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
204 changes: 101 additions & 103 deletions docs/source/contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,71 +4,36 @@ Thank you for contributing to Manim! However you have decided to contribute or
interact with the community, please always be civil and respect other members
of the community. Manim is a free open source software for mathematical
animations, 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, 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
confusing. 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:
```sh
git 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 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. 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.

```sh
git remote add upstream https://github.com/ManimCommunity/manim.git
Expand All @@ -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
```sh
git 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 commit
them.

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 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. 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`.

![pull-requests-example-manim-community](./_static/pull-requests.PNG)
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.

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

Please make sure you follow the template (this is the default
text 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 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!

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 guidelines
Expand Down
1 change: 1 addition & 0 deletions docs/source/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ information here will make it easier for newcomers to get started using
reference
examples
tutorials
reporting_bugs
contributing

Navigation
Expand Down
3 changes: 3 additions & 0 deletions docs/source/installation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,9 @@ cloned this repo, run the following:
.. code-block:: bash

python3 -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 the
Expand Down
10 changes: 10 additions & 0 deletions docs/source/installation/troubleshooting.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 --all
37 changes: 37 additions & 0 deletions docs/source/reporting_bugs.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.