docs: some fixes to contribution docs in README (no bug), r=releng-reviewers,hneiva
authorAndrew Halberstadt <ahal@mozilla.com>
Wed, 23 Mar 2022 20:28:11 +0000
changeset 389 8ad78a37ec18fda719479cfd085a2f3a6db16eb6
parent 388 0d0a66e79086b569061900b7e6abe0fcffd7f2c6
child 390 c7307e70082afff873540fbbcbf59e029a1e024b
push id214
push userahalberstadt@mozilla.com
push dateWed, 23 Mar 2022 20:30:16 +0000
treeherdertaskgraph@8ad78a37ec18 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersreleng-reviewers, hneiva
docs: some fixes to contribution docs in README (no bug), r=releng-reviewers,hneiva * Remove blurb about 'sphinx-apidoc' as re-running this will now overwrite things. It's not hard to maintain this manually since we rarely add new modules. * Move 'release' docs to the bottom (most contributors can't do this anyway) * Correct some mistakes in 'dependencies' section. Depends on D141850 Differential Revision: https://phabricator.services.mozilla.com/D141851
README.rst
--- a/README.rst
+++ b/README.rst
@@ -40,37 +40,16 @@ repository, activate a virtualenv and in
 
 .. code-block::
 
   hg clone https://hg.mozilla.org/ci/taskgraph
   cd taskgraph
   python -m venv taskgraph && source taskgraph/bin/activate
   pip install -r requirements/dev.txt
   $ python setup.py develop
-  
-Releasing
----------
-
-In order to release a new version of Taskgraph, you will need permission to the
-`taskcluster-taskgraph`_ project in PyPI.
-The following are **required** steps:
-
-  1. Update ``CHANGELOG.md``
-  2. Update ``version`` in ``setup.py``
-  3. Commit, and land the above changes
-  4. Make sure your ``hg status`` is clean
-  5. Checkout the latest public revision ``hg checkout -r 'last(public())'``
-  6. Pull latest revision ``hg pull -u``
-  7. Verify ``hg ident`` outputs the desired revision
-  8. Remove previously packaged releases ``rm -rf ./dist/*``
-  9. Package the app ``python setup.py sdist bdist_wheel``
-  10. Upload to PyPI using `twine`_ ``twine upload dist/*`` providing your username and password
-
-.. _taskcluster-taskgraph: https://pypi.org/project/taskcluster-taskgraph/
-.. _twine: https://pypi.org/project/twine/
 
 Running Tests and Linters
 -------------------------
 
 Tests are run with the `pytest <https://docs.pytest.org>`_ framework:
 
 .. code-block::
 
@@ -102,44 +81,67 @@ This will start a live server that autom
 documentation file. Alternatively you can generate static docs under the
 ``docs/_build`` directory:
 
 .. code-block::
 
   make html
 
 Taskgraph also uses the ``autodoc`` extension to generate an API reference.
-When new modules are created, the API docs need to be regenerated using the
-following command:
-
-.. code-block::
-
-  sphinx-apidoc -o docs/source --ext-autodoc -H "API Reference" src/taskgraph "src/taskgraph/test"
+When new modules are created, be sure to add an ``autodoc`` directive for
+them in the source reference.
 
 .. _Sphinx: https://www.sphinx-doc.org
 
 Managing Dependencies
 ---------------------
 
-.. warning:: 
+.. warning::
    Ensure you always update packages using the minimum supported Python.
    Otherwise you may break the workflow of people trying to develop Taskgraph
    with an older version of Python. The `pyenv`_ tool can help with managing
    multiple Python versions at once.
 
 To help lock dependencies, Taskgraph uses a tool called `pip-compile-multi`_.
 To add or update a dependency first edit the relevant ``.in`` file under the
 ``requirements`` directory. If the dependency is needed by the actual Taskgraph
 library, edit ``requirements/base.in``. If it's required by the CI system, edit
 ``requirements/test.in``. And if it's only needed for developing Taskgraph,
 edit ``requirements/dev.in``.
 
 Next run the following command from the repository root:
 
 .. code-block::
 
-  pip-compile-multi -g base -g test -g dev --allow-unsafe -P <package>
+  pip-compile-multi -g base -g test -g dev --allow-unsafe
 
-Where ``<package>`` is the name of the package you added or updated. Note the
-``-P`` flag can be passed multiple times if multiple dependencies were changed.
+If you'd like to add a new package without upgrading any of the existing ones,
+you can run:
+
+.. code-block::
+
+  pip-compile-multi -g base -g test -g dev --allow-unsafe --no-upgrade
 
 .. _pyenv: https://github.com/pyenv/pyenv
 .. _pip-compile-multi: https://pip-compile-multi.readthedocs.io/en/latest/
+
+Releasing
+---------
+
+In order to release a new version of Taskgraph, you will need permission to the
+`taskcluster-taskgraph`_ project in PyPI.
+The following are **required** steps:
+
+  1. Update ``CHANGELOG.md``
+  2. Update ``version`` in ``setup.py``
+  3. Commit, and land the above changes
+  4. Make sure your ``hg status`` is clean
+  5. Checkout the latest public revision ``hg checkout -r 'last(public())'``
+  6. Pull latest revision ``hg pull -u``
+  7. Verify ``hg ident`` outputs the desired revision
+  8. Remove previously packaged releases ``rm -rf ./dist/*``
+  9. Package the app ``python setup.py sdist bdist_wheel``
+  10. Upload to PyPI using `twine`_ ``twine upload dist/*`` providing your
+      username and API token
+
+.. _taskcluster-taskgraph: https://pypi.org/project/taskcluster-taskgraph/
+.. _twine: https://pypi.org/project/twine/
+