Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Refactoring gitwash #23588

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 5 commits into from
Dec 5, 2022
Merged

Refactoring gitwash #23588

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
0600dae
Refactoring gitwash
melissawm Aug 2, 2022
7c1e037
Addressing review comments
melissawm Aug 28, 2022
e592e7a
Addressing more review suggestions
melissawm Aug 29, 2022
270fdde
Reorganizing content
melissawm Dec 1, 2022
1b7510d
Addressing more review comments
melissawm Dec 1, 2022
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
88 changes: 86 additions & 2 deletions doc/devel/coding_guide.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,92 @@
Pull request guidelines
***********************

Pull requests (PRs) are the mechanism for contributing to Matplotlibs code and
documentation.
`Pull requests (PRs) on GitHub
<https://docs.github.com/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests>`__
are the mechanism for contributing to Matplotlib's code and documentation.

It is recommended to check that your contribution complies with the following
rules before submitting a pull request:

* If your pull request addresses an issue, please use the title to describe the
issue (e.g. "Add ability to plot timedeltas") and mention the issue number
in the pull request description to ensure that a link is created to the
original issue (e.g. "Closes #8869" or "Fixes #8869"). This will ensure the
original issue mentioned is automatically closed when your PR is merged. See
`the GitHub documentation
<https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue>`__
for more details.

* Formatting should follow the recommendations of PEP8_, as enforced by
flake8_. You can check flake8 compliance from the command line with ::

python -m pip install flake8
flake8 /path/to/module.py

or your editor may provide integration with it. Note that Matplotlib
intentionally does not use the black_ auto-formatter (1__), in particular due
to its unability to understand the semantics of mathematical expressions
(2__, 3__).

.. _PEP8: https://www.python.org/dev/peps/pep-0008/
.. _flake8: https://flake8.pycqa.org/
.. _black: https://black.readthedocs.io/
.. __: https://github.com/matplotlib/matplotlib/issues/18796
.. __: https://github.com/psf/black/issues/148
.. __: https://github.com/psf/black/issues/1984

* All public methods should have informative docstrings with sample usage when
appropriate. Use the :ref:`docstring standards <writing-docstrings>`.

* For high-level plotting functions, consider adding a simple example either in
the ``Example`` section of the docstring or the
:ref:`examples gallery <gallery>`.

* Changes (both new features and bugfixes) should have good test coverage. See
:ref:`testing` for more details.

* Import the following modules using the standard scipy conventions::

import numpy as np
import numpy.ma as ma
import matplotlib as mpl
import matplotlib.pyplot as plt
import matplotlib.cbook as cbook
import matplotlib.patches as mpatches

In general, Matplotlib modules should **not** import `.rcParams` using ``from
matplotlib import rcParams``, but rather access it as ``mpl.rcParams``. This
is because some modules are imported very early, before the `.rcParams`
singleton is constructed.

* If your change is a major new feature, add an entry to the ``What's new``
section by adding a new file in ``doc/users/next_whats_new`` (see
:file:`doc/users/next_whats_new/README.rst` for more information).

* If you change the API in a backward-incompatible way, please document it in
:file:`doc/api/next_api_changes/behavior`, by adding a new file with the
naming convention ``99999-ABC.rst`` where the pull request number is followed
by the contributor's initials. (see :file:`doc/api/api_changes.rst` for more
information)

* See below for additional points about :ref:`keyword-argument-processing`, if
applicable for your pull request.

.. note::

The current state of the Matplotlib code base is not compliant with all
of these guidelines, but we expect that enforcing these constraints on all
new contributions will move the overall code base quality in the right
direction.


.. seealso::

* :ref:`coding_guidelines`
* :ref:`testing`
* :ref:`documenting-matplotlib`



Summary for pull request authors
================================
Expand Down
103 changes: 11 additions & 92 deletions doc/devel/contributing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,20 @@
Contributing
============

You've discovered a bug or something else you want to change
in Matplotlib — excellent!

You've worked out a way to fix it — even better!

You want to tell us about it — best of all!

This project is a community effort, and everyone is welcome to
contribute. Everyone within the community
is expected to abide by our
`code of conduct <https://github.com/matplotlib/matplotlib/blob/main/CODE_OF_CONDUCT.md>`_.

The project is hosted on
https://github.com/matplotlib/matplotlib
Below, you can find a number of ways to contribute, and how to connect with the
Matplotlib community.

Get Connected
=============
Expand Down Expand Up @@ -192,96 +199,8 @@ A brief overview is:
Finally, go to the web page of your fork of the Matplotlib repo, and click
'Pull request' to send your changes to the maintainers for review.

.. seealso::

* `Git documentation <https://git-scm.com/doc>`_
* `Git-Contributing to a Project <https://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project>`_
* `Introduction to GitHub <https://lab.github.com/githubtraining/introduction-to-github>`_
* :ref:`development-workflow` for best practices for Matplotlib
* :ref:`using-git`

Contributing pull requests
--------------------------

It is recommended to check that your contribution complies with the following
rules before submitting a pull request:

* If your pull request addresses an issue, please use the title to describe the
issue and mention the issue number in the pull request description to ensure
that a link is created to the original issue.

* All public methods should have informative docstrings with sample usage when
appropriate. Use the `numpy docstring standard
<https://numpydoc.readthedocs.io/en/latest/format.html>`_.

* Formatting should follow the recommendations of PEP8_, as enforced by
flake8_. You can check flake8 compliance from the command line with ::

python -m pip install flake8
flake8 /path/to/module.py

or your editor may provide integration with it. Note that Matplotlib
intentionally does not use the black_ auto-formatter (1__), in particular due
to its inability to understand the semantics of mathematical expressions
(2__, 3__).

.. _PEP8: https://www.python.org/dev/peps/pep-0008/
.. _flake8: https://flake8.pycqa.org/
.. _black: https://black.readthedocs.io/
.. __: https://github.com/matplotlib/matplotlib/issues/18796
.. __: https://github.com/psf/black/issues/148
.. __: https://github.com/psf/black/issues/1984

* Each high-level plotting function should have a simple example in the
``Example`` section of the docstring. This should be as simple as possible
to demonstrate the method. More complex examples should go in the
``examples`` tree.

* Changes (both new features and bugfixes) should have good test coverage. See
:ref:`testing` for more details.

* Import the following modules using the standard scipy conventions::

import numpy as np
import numpy.ma as ma
import matplotlib as mpl
import matplotlib.pyplot as plt
import matplotlib.cbook as cbook
import matplotlib.patches as mpatches

In general, Matplotlib modules should **not** import `.rcParams` using ``from
matplotlib import rcParams``, but rather access it as ``mpl.rcParams``. This
is because some modules are imported very early, before the `.rcParams`
singleton is constructed.

* If your change is a major new feature, add an entry to the ``What's new``
section by adding a new file in ``doc/users/next_whats_new`` (see
:file:`doc/users/next_whats_new/README.rst` for more information).

* If you change the API in a backward-incompatible way, please document it in
:file:`doc/api/next_api_changes/behavior`, by adding a new file with the
naming convention ``99999-ABC.rst`` where the pull request number is followed
by the contributor's initials. (see :file:`doc/api/api_changes.rst` for more
information)

* See below for additional points about :ref:`keyword-argument-processing`, if
applicable for your pull request.

.. note::

The current state of the Matplotlib code base is not compliant with all
of those guidelines, but we expect that enforcing those constraints on all
new contributions will move the overall code base quality in the right
direction.


.. seealso::

* :ref:`coding_guidelines`
* :ref:`testing`
* :ref:`documenting-matplotlib`


For more detailed instructions on how to set up Matplotlib for development and
best practices for contribution, see :ref:`installing_for_devs`.


.. _contributing_documentation:
Expand Down
51 changes: 38 additions & 13 deletions doc/devel/development_setup.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,38 +9,63 @@ To set up Matplotlib for development follow these steps:
.. contents::
:local:

Fork the Matplotlib repository
==============================

Matplotlib is hosted at https://github.com/matplotlib/matplotlib.git. If you
plan on solving issues or submit pull requests to the main Matplotlib
repository, you should first *fork* this repository by visiting
https://github.com/matplotlib/matplotlib.git and clicking on the
``Fork`` button on the top right of the page (see
`the GitHub documentation <https://docs.github.com/get-started/quickstart/fork-a-repo>`__ for more details.)

Retrieve the latest version of the code
=======================================

Matplotlib is hosted at https://github.com/matplotlib/matplotlib.git.

You can retrieve the latest sources with the command (see
:ref:`set-up-fork` for more details)
Now that your fork of the repository lives under your GitHub username, you can
retrieve the latest sources with one of the following commands (where your
should replace ``<your-username>`` with your GitHub username):

.. tab-set::

.. tab-item:: https

.. code-block:: bash

git clone https://github.com/matplotlib/matplotlib.git
git clone https://github.com/<your-username>/matplotlib.git

.. tab-item:: ssh

.. code-block:: bash

git clone [email protected]:matplotlib/matplotlib.git
git clone [email protected]:<your-username>/matplotlib.git

This requires you to setup an `SSH key`_ in advance, but saves you from
typing your password at every connection.

.. _SSH key: https://docs.github.com/en/authentication/connecting-to-github-with-ssh


This will place the sources in a directory :file:`matplotlib` below your
current working directory. Change into this directory::
current working directory, set up the ``origin`` remote to point to your own
fork, and set up the ``upstream`` remote to point to the Matplotlib main
repository (see also `Managing remote repositories <https://docs.github.com/en/get-started/getting-started-with-git/managing-remote-repositories>`__.)
Change into this directory before continuing::

cd matplotlib

.. note::

For more information on ``git`` and ``GitHub``, check the following resources.

* `Git documentation <https://git-scm.com/doc>`_
* `GitHub-Contributing to a Project <https://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project>`_
* `Introduction to GitHub <https://lab.github.com/githubtraining/introduction-to-github>`_
* :ref:`using-git`
* :ref:`git-resources`
* `Installing git <https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`_
* https://tacaswell.github.io/think-like-git.html
* https://tom.preston-werner.com/2009/05/19/the-git-parable.html

.. _dev-environment:

Expand Down Expand Up @@ -86,12 +111,8 @@ The simplest way to do this is to use either Python's virtual environment

Remember to activate the environment whenever you start working on Matplotlib.

Install additional development dependencies
===========================================
See :ref:`development-dependencies`.

Install Matplotlib in editable mode
===================================
Installing Matplotlib in editable mode
======================================
Install Matplotlib in editable mode from the :file:`matplotlib` directory
using the command ::

Expand All @@ -105,6 +126,10 @@ true for ``*.py`` files. If you change the C-extension source (which might
also happen if you change branches) you will have to re-run
``python -m pip install -ve .``

Install additional development dependencies
===========================================
See :ref:`development-dependencies`.

Install pre-commit hooks (optional)
===================================
`pre-commit <https://pre-commit.com/>`_ hooks automatically check flake8 and
Expand Down
Loading