Skip to content
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

Contrib guide: more restructuring #1461

Merged
merged 3 commits into from
Nov 3, 2024
Merged

Contrib guide: more restructuring #1461

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
be7cd9f
contrib guide: more restructuring
nedbat Oct 28, 2024
e3dd83e
review comment fixes
nedbat Oct 31, 2024
d771c82
table tweaks
nedbat Nov 1, 2024
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
2 changes: 2 additions & 0 deletions contrib/code/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. _c_code:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This made me think of C the language.

Are these c_ prefixes short for "contrib" and temporary whilst still a draft in parallel with the old devguide?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, exactly. I maybe should have explained that.


==================
Code contributions
==================
Expand Down
2 changes: 1 addition & 1 deletion contrib/project/core-team/committing.rst → contrib/core-team/committing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,4 @@
[This is the existing core developers :ref:`committing` page from the devguide. We'll
adjust "core developer" to "core team" where appropriate.]

.. include:: ../../../core-developers/committing.rst
.. include:: ../../core-developers/committing.rst
2 changes: 1 addition & 1 deletion contrib/project/core-team/developer-log.rst → contrib/core-team/developer-log.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,4 @@
[This is the existing core developers :ref:`developer-log` page from the devguide. We'll
adjust "core developer" to "core team" where appropriate.]

.. include:: ../../../core-developers/developer-log.rst
.. include:: ../../core-developers/developer-log.rst
2 changes: 1 addition & 1 deletion contrib/project/core-team/experts.rst → contrib/core-team/experts.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,4 @@
[This is the existing core developers :ref:`experts` page from the devguide. We'll
adjust "core developer" to "core team" where appropriate.]

.. include:: ../../../core-developers/experts.rst
.. include:: ../../core-developers/experts.rst
0 contrib/project/core-team/index.rst → contrib/core-team/index.rst
View file
Open in desktop
File renamed without changes.
2 changes: 1 addition & 1 deletion contrib/project/core-team/join-team.rst → contrib/core-team/join-team.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,5 +12,5 @@ adjust "core developer" to "core team" where appropriate.]
How to join the core team
=========================

.. include:: ../../../core-developers/become-core-developer.rst
.. include:: ../../core-developers/become-core-developer.rst
:start-line: 7
2 changes: 1 addition & 1 deletion contrib/project/core-team/motivations.rst → contrib/core-team/motivations.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,4 @@
[This is the existing core developers :ref:`motivations` page from the devguide. We'll
adjust "core developer" to "core team" where appropriate.]

.. include:: ../../../core-developers/motivations.rst
.. include:: ../../core-developers/motivations.rst
2 changes: 1 addition & 1 deletion ...ib/project/core-team/responsibilities.rst → contrib/core-team/responsibilities.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,4 @@
[This is the existing core developers :ref:`responsibilities` page from the devguide. We'll
adjust "core developer" to "core team" where appropriate.]

.. include:: ../../../core-developers/responsibilities.rst
.. include:: ../../core-developers/responsibilities.rst
2 changes: 2 additions & 0 deletions contrib/doc/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. _c_docs:

===========================
Documentation contributions
===========================
Expand Down
2 changes: 2 additions & 0 deletions contrib/get-started/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. _c_gettingstarted:

===============
Getting started
===============
Expand Down
112 changes: 102 additions & 10 deletions contrib/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,28 +1,116 @@
.. _c_root:

==================================
Python Contributor's Guide (draft)
==================================

.. raw:: html

<script>
document.addEventListener('DOMContentLoaded', function() {
activateTab(getOS());
});
</script>
<style>
table.docutils td { vertical-align: top; }
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps we should move this to _static/devguide_overrides.css?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I didn't know about that file. I think tables should default to top-aligned, but idk if this will affect other things badly as a global setting.

</style>


.. important::

|draft|

|purpose|


This guide is a comprehensive resource for contributing to Python.
[Open question: how to divide content between this Introduction and the
:ref:`introduction <c_intro>`?]

This guide is a comprehensive resource for :ref:`contributing <contributing>`
to Python_ -- for both new and experienced contributors. It is :ref:`maintained
<devguide>` by the same community that maintains Python. We welcome your
contributions to Python!

We encourage everyone to contribute to Python. This guide should have
everything you need to get started and be productive. If you still have
questions after reviewing the material in this guide, the `Core Python
Mentorship`_ group is available to help you through the process.

There are a number of ways to contribute including code, documentation, and
triaging issues. We've organized this guide to provide specifics based on the
type of activity you'll be engaged in.


Using this guide
================

We recommend reading this guide as needed. You can stop where you feel
comfortable and begin contributing immediately without reading and
understanding everything. If you do choose to skip around this guide, be aware
that it is written assuming preceding sections have been read so you may need
to backtrack to fill in missing concepts and terminology.

.. note::
This is a draft of a new organization for the devguide, turning it into a
Contributor's Guide.
No matter what kind of contribution you'll be making, you should start with
these common sections:

[Much of the devguide home page will be here. The Quick Start will be updated
to distinguish code vs documentation contributions, and moved to those
sections. Other changes will be made to explain the different types of
contribution and how to navigate the guide for your own type.]
* :ref:`c_intro`
* :ref:`c_project`
* :ref:`c_gettingstarted`

Then choose a path based on your type of activity:

*[The original table on the devguide home had a fourth column for Core
Developers. That made the table wider and more confusing. I don't think core
team members need a quick intro path since they will have been through the
devguide before.]*

*[I haven't adjusted the links in the table yet other than to add a link to the
major section at the top of each column.]*

.. list-table::
Copy link
Member

@hugovk hugovk Oct 31, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm trying to think which is better, lists inside a table, or smaller cells, from an accessibility point of view, and I'm not sure :)

The new table of lists might be better, because there's no relation between the old cells that happen to be next to each other; that is, the old way was just for presentation and not structure. So I think the list might be better?

image

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Other people I've talked with definitely felt like the one-link-per-cell style of the current home page table is misleading because the rows have no meaning.

:widths: 10 10 10
:header-rows: 1

* - Triaging
- Documentation
- Code
* -
:ref:`c_triage`

* :ref:`tracker`
* :ref:`triaging`
* :ref:`helptriage`
* :ref:`experts`
* :ref:`labels`
* :ref:`gh-faq`
* :ref:`triage-team`
-
:ref:`c_docs`

* :ref:`docquality`
* :ref:`documenting`
* :ref:`style-guide`
* :ref:`rst-primer`
* :ref:`translating`
* :ref:`devguide`
-
:ref:`c_code`

* :ref:`setup`
* :ref:`help`
* :ref:`pullrequest`
* :ref:`runtests`
* :ref:`fixingissues`
* :ref:`communication`
* :ref:`gitbootcamp`
* :ref:`devcycle`

[The contents had been listed below here. It was very long, and I don't think
it was helpful. The left sidebar has the contents.]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, I found it helpful: I often cmd+F on the homepage to find something, which won't work with a collapsed left sidebar.

It is a little unusual to have a large table-of-contents on a page, although it is out of the way at the bottom of the page, and not so big as to be a performance problem (like, we definitely wouldn't want the whole CPython TOC).

But it's not the end of the world to remove it if no one else wants it :)

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it is fine to leave at the very bottom.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can leave it.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I put it back, but not as deep as before, so it's not so long.


.. toctree::
:maxdepth: 2
:maxdepth: 1
:hidden:

contrib-plan
intro/index
Expand All @@ -31,6 +119,10 @@ contribution and how to navigate the guide for your own type.]
triage/index
code/index
doc/index
core-team/index
user-success
security
outreach


.. _Python: https://www.python.org/
.. _Core Python Mentorship: https://www.python.org/dev/core-mentorship/
19 changes: 19 additions & 0 deletions contrib/intro/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. _c_intro:

============
Introduction
============
Expand All @@ -10,9 +12,26 @@ Introduction



[Open question: how to divide content between this Introduction and the
:ref:`home page <c_root>`?]

Welcome!

New to open source?
===================

Python is an open source project, with culture and techniques from the broader
open source world. You might find it helpful to read about open source in
general. A number of individuals from the Python community have contributed to
a series of excellent guides at `Open Source Guides
<https://opensource.guide/>`_.

Anyone will find the following guides useful:

* `How to Contribute to Open Source <https://opensource.guide/how-to-contribute/>`_
* `Building Welcoming Communities <https://opensource.guide/building-community/>`_


Healthy Collaboration
hugovk marked this conversation as resolved.
Show resolved Hide resolved
=====================

Expand Down
10 changes: 10 additions & 0 deletions contrib/project/generative-ai.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
.. important::

|draft|

|purpose|


[This is the existing :ref:`generative-ai` page from the devguide.]

.. include:: ../../getting-started/generative-ai.rst
5 changes: 4 additions & 1 deletion contrib/project/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. _c_project:

===================
The CPython project
===================
Expand All @@ -19,7 +21,8 @@ moving parts, who is involved, how do they interact?]

conduct
roles
core-team/index
governance
generative-ai.rst
github
channels
outreach
0 contrib/outreach.rst → contrib/project/outreach.rst
View file
Open in desktop
File renamed without changes.
2 changes: 2 additions & 0 deletions contrib/triage/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. _c_triage:

===================
Issues and triaging
===================
Expand Down
Loading