Repository navigation
DOC: Add conda environment instructions to developers guide #21611
Description
Just so we don't lose track of adding this to the docs at some point.
I'll add a description how to use this later to the dev docs. But basically following the instuctions in the file is sufficient.
Originally posted by @timhoffm in #17096 (comment)
I found reading through the installation instructions quite verbose. I think it is good information to keep in the documentation, but intimidating for someone just coming onto the project. My suggestion would be to add a top-level "Quickly get set up" section using the conda environment from the repo and explaining how to install and use pre-commit from #21583. An opinionated set of instructions up front and then additional details for other architectures and configurations following that.
# fork the matplotlib repository to your username
git clone git@github.com/your-user-name/matplotlib.git
cd matplotlib
git remote add upstream https://github.com/matplotlib/matplotlib.git
# Install dependencies
conda env create -f environment.yml
conda activate mpl-dev
pre-commit install
pip install -e .
# checkout a new feature branch
git checkout -b my-new-feature
# Make changes to files (including new tests!) and test your addition
pytest lib/matplotlib/tests/test_file_you_changed.py
# Commit with a message explaining what you have changed
git add any-files-you-changed
git commit
# Committing will run automatic code-style checks and may fail and explain what you need to change
# Push to remote repository
git push --set-upstream origin my-new-feature
# Go to GitHub and open a Pull Request for your new feature!
Activity
jklymak commented on Nov 12, 2021
I always just spell that git commit -a -m "My message" Then you don't need to keep track of what you changed.
timhoffm commented on Nov 12, 2021
Which you can shorten to `git commit -am "My message" (more FYI); I think there’s some value in spelling out add and commit for inexperienced users. But no strong opinion.
jklymak commented on Nov 12, 2021
I don't feel strongly about it. I'll confess until today I didn't even realize that you could stage files just by "adding" them.
greglucas commented on Nov 13, 2021
In this section, I think the user that would be targeted would be someone with very little (if any) git experience. So, being explicit is probably better. More advanced users will already know the git commands and be able to translate this to their own workflow.
I also noticed that we actually already have a pretty good (maybe too verbose compared to what I'm proposing here though) "development workflow" site https://matplotlib.org/devdocs/devel/gitwash/development_workflow.html, and it is buried about 3-levels deep in the docs.
I see two possibilities for this:
I don't have any strong opinions here, but would probably lean towards 2. If there is a short list of instructions that will be more approachable and new contributors will follow those instructions, versus the long explanations which many contributors (myself included 😉 ) probably fail to read.
timhoffm commented on Nov 13, 2021
The gitwash folder and everything below is from the gitwash project, which many years ago was formed to provide pluggable git instructions to included in project docs. It’s unmaintained. We’ve had discussions whether to remove it, but I don’t remember if we decided something. Personally, I’m in favor of removing. It’s a lot of information but not very targeted.
Note also that I’ve started a similar attempt at #20102 .
DOC: Add conda environment instructions to developers guide.
DOC: Add conda environment instructions to developers guide.
DOC: Add conda environment instructions to developers guide.
DOC: Add conda environment instructions to developers guide.
DOC: Add conda environment instructions to developers guide.
DOC: Add conda environment instructions to developers guide.
DOC: Add conda environment instructions to developers guide.
DOC: Add conda environment instructions to developers guide.
DOC: Add conda environment instructions to developers guide.
DOC: Add conda environment instructions to developers guide.
DOC: Add conda environment instructions to developers guide.
DOC: Add conda environment instructions to developers guide.
DOC: Add conda environment instructions to developers guide.
DOC: Add conda environment instructions to developers guide.