DOC: rephrase the role of core devs (#28912)

Co-authored-by: Jérémie du Boisberranger <[email protected]> Co-authored-by: Adrin Jalali <[email protected]>
scikit-learn · May 2, 2024 · 8f96794 · 8f96794
1 parent 4c89b3b
commit 8f96794
Show file tree

Hide file tree

Showing 6 changed files with 70 additions and 62 deletions.
diff --git a/build_tools/generate_authors_table.py b/build_tools/generate_authors_table.py
@@ -214,11 +214,13 @@ def generate_list(contributors):
         documentation_team,
     ) = get_contributors()
 
-    with open(REPO_FOLDER / "doc" / "authors.rst", "w+", encoding="utf-8") as rst_file:
+    with open(
+        REPO_FOLDER / "doc" / "maintainers.rst", "w+", encoding="utf-8"
+    ) as rst_file:
         rst_file.write(generate_table(core_devs))
 
     with open(
-        REPO_FOLDER / "doc" / "authors_emeritus.rst", "w+", encoding="utf-8"
+        REPO_FOLDER / "doc" / "maintainers_emeritus.rst", "w+", encoding="utf-8"
     ) as rst_file:
         rst_file.write(generate_list(emeritus))
 

diff --git a/doc/about.rst b/doc/about.rst
@@ -22,13 +22,27 @@ Governance
 The decision making process and governance structure of scikit-learn is laid
 out in the :ref:`governance document <governance>`.
 
-Authors
--------
+.. The "author" anchors below is there to ensure that old html links (in
+   the form of "about.html#author" still work)
+
+.. _authors:
+
+The people behind scikit-learn
+-------------------------------
 
-The following people are currently core contributors to scikit-learn's development
-and maintenance:
+Scikit-learn is a community project, developed by a large group of
+people, all across the world. A few teams, listed below, have central
+roles, however a more complete list of contributors can be found `on
+github
+<https://github.com/scikit-learn/scikit-learn/graphs/contributors>`__.
 
-.. include:: authors.rst
+Maintainers Team
+................
+
+The following people are currently maintainers, in charge of
+consolidating scikit-learn's development and maintenance:
+
+.. include:: maintainers.rst
 
 Please do not email the authors directly to ask for assistance or report issues.
 Instead, please see `What's the best way to ask questions about scikit-learn
@@ -40,14 +54,14 @@ in the FAQ.
    :ref:`How you can contribute to the project <contributing>`
 
 Documentation Team
-------------------
+..................
 
 The following people help with documenting the project:
 
 .. include:: documentation_team.rst
 
 Contributor Experience Team
----------------------------
+...........................
 
 The following people are active contributors who also help with
 :ref:`triaging issues <bug_triaging>`, PRs, and general
@@ -56,7 +70,7 @@ maintenance:
 .. include:: contributor_experience_team.rst
 
 Communication Team
-------------------
+..................
 
 The following people help with :ref:`communication around scikit-learn
 <communication_team>`.
@@ -70,7 +84,7 @@ Emeritus Core Developers
 The following people have been active contributors in the past, but are no
 longer active in the project:
 
-.. include:: authors_emeritus.rst
+.. include:: maintainers_emeritus.rst
 
 Emeritus Communication Team
 ---------------------------

diff --git a/doc/governance.rst b/doc/governance.rst
@@ -58,56 +58,47 @@ members and recant their rights until they become active again. The list of
 members, active and emeritus (with dates at which they became active) is public
 on the scikit-learn website.
 
-The following teams form the core contributors group.
-
-
-Contributor Experience Team
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The contributor experience team improves the experience of contributors by
-helping with the triage of issues and pull requests, as well as noticing any
-repeating patterns where people might struggle, and to help with improving
-those aspects of the project.
-
-To this end, they have the required permissions on github to label and close
-issues. :ref:`Their work <bug_triaging>` is crucial to improve the
-communication in the project and limit the crowding of the issue tracker.
-
-.. _communication_team:
-
-Communication team
-~~~~~~~~~~~~~~~~~~
-
-Members of the communication team help with outreach and communication
-for scikit-learn. The goal of the team is to develop public awareness of
-scikit-learn, of its features and usage, as well as branding.
-
-For this, they can operate the scikit-learn accounts on various social networks
-and produce materials. They also have the required rights to our blog
-repository and other relevant accounts and platforms.
-
-Documentation team
-~~~~~~~~~~~~~~~~~~
-
-Members of the documentation team engage with the documentation of the project
-among other things. They might also be involved in other aspects of the
-project, but their reviews on documentation contributions are considered
-authoritative, and can merge such contributions.
-
-To this end, they have permissions to merge pull requests in scikit-learn's
-repository.
-
-Maintainers
-~~~~~~~~~~~
-
-Maintainers are community members who have shown that they are dedicated to the
-continued development of the project through ongoing engagement with the
-community. They have shown they can be trusted to maintain scikit-learn with
-care. Being a maintainer allows contributors to more easily carry on with their
-project related activities by giving them direct access to the project's
-repository. Maintainers are expected to review code contributions, merge
-approved pull requests, cast votes for and against merging a pull-request,
-and to be involved in deciding major changes to the API.
+The following teams form the core contributors group:
+
+* **Contributor Experience Team**
+  The contributor experience team improves the experience of contributors by
+  helping with the triage of issues and pull requests, as well as noticing any
+  repeating patterns where people might struggle, and to help with improving
+  those aspects of the project.
+
+  To this end, they have the required permissions on github to label and close
+  issues. :ref:`Their work <bug_triaging>` is crucial to improve the
+  communication in the project and limit the crowding of the issue tracker.
+
+  .. _communication_team:
+
+* **Communication Team**
+  Members of the communication team help with outreach and communication
+  for scikit-learn. The goal of the team is to develop public awareness of
+  scikit-learn, of its features and usage, as well as branding.
+
+  For this, they can operate the scikit-learn accounts on various social networks
+  and produce materials. They also have the required rights to our blog
+  repository and other relevant accounts and platforms.
+
+* **Documentation Team**
+  Members of the documentation team engage with the documentation of the project
+  among other things. They might also be involved in other aspects of the
+  project, but their reviews on documentation contributions are considered
+  authoritative, and can merge such contributions.
+
+  To this end, they have permissions to merge pull requests in scikit-learn's
+  repository.
+
+* **Maintainers Team**
+  Maintainers are community members who have shown that they are dedicated to the
+  continued development of the project through ongoing engagement with the
+  community. They have shown they can be trusted to maintain scikit-learn with
+  care. Being a maintainer allows contributors to more easily carry on with their
+  project related activities by giving them direct access to the project's
+  repository. Maintainers are expected to review code contributions, merge
+  approved pull requests, cast votes for and against merging a pull-request,
+  and to be involved in deciding major changes to the API.
 
 Technical Committee
 -------------------

diff --git a/doc/authors.rst → doc/maintainers.rst b/doc/authors.rst → doc/maintainers.rst
diff --git a/doc/authors_emeritus.rst → doc/maintainers_emeritus.rst b/doc/authors_emeritus.rst → doc/maintainers_emeritus.rst
diff --git a/doc/templates/index.html b/doc/templates/index.html
@@ -189,7 +189,8 @@ <h4 class="sk-landing-call-header">News</h4>
       <div class="col-md-4">
         <h4 class="sk-landing-call-header">Community</h4>
         <ul class="sk-landing-call-list list-unstyled">
-        <li><strong>About us:</strong> See <a href="about.html#people">authors</a> and <a href="{{ contributing_link }}" {{ contributing_attrs }}>contributing</a></li>
+        <li><strong>About us:</strong> See <a
+href="about.html#the-people-behind-scikit-learn">people</a> and <a href="{{ contributing_link }}" {{ contributing_attrs }}>contributing</a></li>
         <li><strong>More Machine Learning:</strong> Find <a href="related_projects.html">related projects</a></li>
         <li><strong>Questions?</strong> See <a href="faq.html">FAQ</a>, <a href="support.html">support</a>, and <a href="https://stackoverflow.com/questions/tagged/scikit-learn">stackoverflow</a></li>
         <li><strong>Subscribe to the</strong> <a href="https://mail.python.org/mailman/listinfo/scikit-learn">mailing list</a></li>