8000 DOC: Add conda environment instructions to developers guide · Issue #21611 · matplotlib/matplotlib · GitHub
[go: up one dir, main page]
Skip to content

DOC: Add conda environment instructions to developers guide #21611

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

Jump to bottom
Closed
greglucas opened this issue Nov 12, 2021 · 5 comments
Closed

DOC: Add conda environment instructions to developers guide #21611

greglucas opened this issue Nov 12, 2021 · 5 comments
Labels
Documentation
Milestone
v3.6.0

Comments

@greglucas
Copy link
Contributor
greglucas commented Nov 12, 2021 •
edited
Loading

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!
@jklymak
Copy link
Member
jklymak commented Nov 12, 2021 
# Make changes and commit with a message explaining what you have changed
git add any-files-you-changed
git commit

I always just spell that git commit -a -m "My message" Then you don't need to keep track of what you changed.

@timhoffm
Copy link
Member

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
Copy link
Member
jklymak commented 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
Copy link
Contributor Author

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:

  1. Add only the conda environment instructions as an additional option here: https://matplotlib.org/devdocs/devel/development_setup.html#creating-a-dedicated-environment
  2. Adding a new section at the top of that page called "Quickstart guide" or something like that. With the dump of commands and one-line explanations above. It would not go into detail like the other workflow pages and be very terse.

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
Copy link
Member

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 .

acatlett8 added a commit to acatlett8/matplotlib that referenced this issue Jul 16, 2022
@acatlett8
DOC: Add conda environment instructions to developers guide.
25bd6bd 
fixes matplotlib#21611
@acatlett8 acatlett8 mentioned this issue Jul 16, 2022
Merged
5 tasks
QuLogic pushed a commit to acatlett8/matplotlib that referenced this issue Aug 10, 2022
@acatlett8 @QuLogic
DOC: Add conda environment instructions to developers guide.
50b921f 
fixes matplotlib#21611
@QuLogic QuLogic added this to the v3.6.0 milestone Aug 10, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation
Projects
None yet
Milestone
v3.6.0
Development

No branches or pull requests
5 participants
@QuLogic @jklymak @timhoffm @oscargus @greglucas
0