Merge pull request #433 from akaihola/doc-update-contributors

CHANGES.rst

@@ -6,8 +6,8 @@ These features will be included in the next release:
 Added
 -----
 - Declare Python 3.11 as supported in package metadata.
-- Document how to set up a development environment and run tests and linters in
-  ``CONTRIBUTING.rst``.
+- Document how to set up a development environment, run tests, run linters and update
+  contributors list in ``CONTRIBUTING.rst``.
 
 Fixed
 -----

CONTRIBUTING.rst

@@ -34,14 +34,58 @@ To speed up review and increase odds for the PR to be accepted, please
 - verify that mypy static type checking passes
 - document new features or changed behavior in ``README.rst``
 - summarize end-user affecting changes in ``CHANGES.rst``
-- add your information in ``CONTRIBUTORS.rst``
+- add your information in ``contributors.yaml``
+- contributor information will be updated to ``CONTRIBUTORS.rst`` and ``README.rst`` in
+  the next release; however, if you have a `GitHub personal access token`_ and want to
+  do this yourself, you can run::
 
-GitHub is configured to use Travis CI on each pull request to
+      python release_tools/update_contributors.py \
+        generate \
+        --token=<your GitHub personal access token> \
+        --modify-readme \
+        --modify-contributors
+
+GitHub is configured to use Github Actions on each pull request to
 
 - run the test suite using Pytest
 - do static type checking using Mypy
+- lint the code using various linters
 - check code formatting using Black
 
+.. _GitHub personal access token:
+
+Creating a GitHub personal access token
+---------------------------------------
+
+Below are the necessary steps to create a GitHub token. You can either go interactively
+step by step, or start straight at step 6. by clicking on the `Generate new token`_
+link. For more information, see `Creating a fine-grained personal access token`_ in
+GitHub Docs.
+
+1. `Verify your email address`_, if it hasn't been verified yet.
+2. In the upper-right corner of any page, click your profile photo, then click Settings_.
+
+   .. image:: https://docs.github.com/assets/cb-34573/images/help/settings/userbar-account-settings.png
+      :width: 150px
+3. In the left sidebar, click `Developer settings`_.
+4. In the left sidebar, under **Personal access tokens**, click `Fine-grained tokens`_.
+5. Click `Generate new token`_.
+6. Under **Token name**, enter "``Update Darker contributors``".
+7. Under **Expiration**, select an expiration for the token.
+8. Under **Description**, type "``Allow darker/release_tools/update_contributors.py to
+   retrieve any user's login, full name and link to avatar picture.``"
+9. Click **Generate token**.
+10. Copy and save the token (you won't be able to see it again), and use it on the
+    ``update_contributors.py`` command line as shown above.
+
+.. _Verify your email address: //docs.github.com/en/github/getting-started-with-github/verifying-your-email-address
+.. _Settings: https://github.com/settings/profile
+.. _Developer settings: https://github.com/settings/apps
+.. _Fine-grained tokens: https://github.com/settings/tokens?type=beta
+.. _Generate new token: https://github.com/settings/personal-access-tokens/new
+.. _Creating a fine-grained personal access token: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-fine-grained-personal-access-token
+
+
 Setting up a development environment
 ====================================
 

CONTRIBUTORS.rst

@@ -4,6 +4,10 @@
 
 (in alphabetic order and with GitHub handles)
 
+.. This file is automatically generated. Please update ``contributors.yaml``
+   instead and see ``CONTRIBUTING.rst`` for instructions on how to update
+   this file.
+
 - Aaron Denney (@wnoise)
 - Aditya Gandra (@agandra)
 - Aljaž Mur Eržen (@aljazerzen)

README.rst

@@ -883,7 +883,9 @@ Thanks goes to these wonderful people (`emoji key`_):
 
 .. raw:: html
 
-   <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
+   <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section
+        This is automatically generated. Please update `contributors.yaml` and
+        see `CONTRIBUTING.rst` for how to re-generate this table. -->
    <table>
      <tr>
        <td align="center">

release_tools/update_contributors.py

@@ -214,7 +214,9 @@ def request(  # type: ignore[override]  # pylint: disable=arguments-differ
 
 
 ALL_CONTRIBUTORS_START = (
-    "   <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->\n"
+    "   <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section\n"
+    "        This is automatically generated. Please update `contributors.yaml` and\n"
+    "        see `CONTRIBUTING.rst` for how to re-generate this table. -->\n"
 )
 ALL_CONTRIBUTORS_END = "   <!-- ALL-CONTRIBUTORS-LIST:END -->"
 
@@ -431,6 +433,10 @@ def write_contributors(text: str) -> None:
 
             (in alphabetic order and with GitHub handles)
 
+            .. This file is automatically generated. Please update ``contributors.yaml``
+               instead and see ``CONTRIBUTING.rst`` for instructions on how to update
+               this file.
+
             {}
             """
         ).format(text),