From 4eb4ab4122b2b974911d4b1f935728cf35e4208c Mon Sep 17 00:00:00 2001 From: Mark Walker Date: Fri, 1 Dec 2023 00:43:56 +0000 Subject: [PATCH] Reorganized the Contributing to Django docs. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This work follows a comprehensive review conducted during the DjangoCon US 2023 sprints. Changes include: - Updated the title of the main page for better alignment with the content. - Removed emojis to enhance accessibility and avoid cultural specificity. - Improved the layout and navigation of contributing documentation. - Unified sections for communication channels and community links. - Grouped resources according to the Diátaxis systematic approach. Co-authored-by: Natalia <124304+nessita@users.noreply.github.com> Co-authored-by: Daniele Procida --- docs/index.txt | 2 +- docs/internals/contributing/index.txt | 146 +++++++++++------- .../contributing/writing-code/index.txt | 62 ++++---- .../contributing/writing-code/javascript.txt | 6 +- 4 files changed, 128 insertions(+), 88 deletions(-) diff --git a/docs/index.txt b/docs/index.txt index 9a5585c29e3..00d62f9f11a 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -325,7 +325,7 @@ Learn about the development process for the Django project itself and about how you can contribute: * **Community:** - :doc:`How to get involved ` | + :doc:`Contributing to Django ` | :doc:`The release process ` | :doc:`Team organization ` | :doc:`The Django source code repository ` | diff --git a/docs/internals/contributing/index.txt b/docs/internals/contributing/index.txt index c96250613ed..6e3fd948ee2 100644 --- a/docs/internals/contributing/index.txt +++ b/docs/internals/contributing/index.txt @@ -6,63 +6,20 @@ Django is a community that lives on its volunteers. As it keeps growing, we always need more people to help others. You can contribute in many ways, either on the framework itself or in the wider ecosystem. -Work on the Django framework -============================ - -The work on Django itself falls into three major areas: - -Writing code 💻 ---------------- - -Fix a bug, or add a new feature. You can make a pull request and see **your -code** in the next version of Django! - -Start from the :doc:`writing-code/index` docs. - -Writing documentation ✍️ ------------------------- - -Django's documentation is one of its key strengths. It's informative and -thorough. You can help to improve the documentation and keep it relevant as the -framework evolves. - -See :doc:`writing-documentation` for more. - -Localizing Django 🗺️ --------------------- - -Django is translated into over 100 languages - There's even some translation -for Klingon?! The i18n team is always looking for translators to help maintain -and increase language reach. - -See :doc:`localizing` to help translate Django. - -Contributing guide 📖 -===================== - -If you think working *with* Django is fun, wait until you start working *on* -it. Really, **ANYONE** can do something to help make Django better and greater! - -This contributing guide contains everything you need to know to help build the -Django web framework. Browse the following sections to find out how: - -.. toctree:: - :maxdepth: 2 - - new-contributors - bugs-and-features - triaging-tickets - writing-code/index - writing-documentation - localizing - committing-code - -Join the Django community ❤️ -============================ +Communication channels +====================== We're passionate about helping Django users make the jump to contributing -members of the community. There are several other ways you can help the -Django community and others to maintain a great ecosystem to work in: +members of the community. Communication is key - working on Django is being +part of a conversation. Join it, to become familiar with what we're doing and +how we talk about it. You'll be able to form relationships with more +experienced contributors who are there to help guide you towards success. + +Join the Django community +------------------------- + +There are several ways you can help the Django community and others to maintain +a great ecosystem to work in: * Join the `Django forum`_. This forum is a place for discussing the Django framework and applications and projects that use it. This is also a good @@ -87,11 +44,86 @@ Django community and others to maintain a great ecosystem to work in: ecosystem of pluggable applications is a big strength of Django, help us build it! -We're looking forward to working with you. Welcome aboard! ⛵️ - .. _posting guidelines: https://code.djangoproject.com/wiki/UsingTheMailingList .. _#django IRC channel: https://web.libera.chat/#django +.. _#django-dev IRC channel: https://web.libera.chat/#django-dev .. _community page: https://www.djangoproject.com/community/ .. _Django Discord server: https://discord.gg/xcRH6mN4fa .. _Django forum: https://forum.djangoproject.com/ .. _register it here: https://www.djangoproject.com/community/add/blogs/ + +Getting started +=============== + +Django encourages and welcomes new contributors, and makes an effort to help +them become experienced, confident contributors to Open Source Software (OSS). +Our documentation contains guidance for first-time contributors, including: + +.. toctree:: + :maxdepth: 1 + + An overview of the contributing process and what's involved. + +Work on the Django framework +============================ + +If you enjoy working *with* Django, wait until you start working *on* it. +Really, **anyone** can do something to improve Django, which will improve the +experience of lots of people! + +The work on Django itself falls into three major areas: + +Contributing code +----------------- + +Fix a bug, or add a new feature. You can make a pull request and see **your +code** in the next version of Django. + +.. toctree:: + :maxdepth: 2 + + writing-code/index + +Contributing documentation +-------------------------- + +Django's documentation is one of its key strengths. It's informative and +thorough. You can help to improve the documentation and keep it relevant as the +framework evolves. + +.. toctree:: + :maxdepth: 2 + + writing-documentation + +Localizing Django +----------------- + +Django is translated into over 100 languages - There's even some translation +for Klingon?! The i18n team is always looking for translators to help maintain +and increase language reach. + +.. toctree:: + :maxdepth: 2 + + localizing + +Other ways of contributing +========================== + +Explore additional avenues of contributing to Django beyond coding. Django's +`ticket tracker`_ is the central hub for managing issues, improvements, and +contributions to Django. It's a valuable resource where you can report bugs you +encounter or assist in triaging existing tickets to ensure a smooth development +workflow. Explore the ways you can make a difference below, and join us in +making Django better for everyone. + +.. toctree:: + :maxdepth: 2 + + bugs-and-features + triaging-tickets + +.. _ticket tracker: https://code.djangoproject.com/ + +We're looking forward to working with you. Welcome aboard! diff --git a/docs/internals/contributing/writing-code/index.txt b/docs/internals/contributing/writing-code/index.txt index 9402c26808f..72cc2645246 100644 --- a/docs/internals/contributing/writing-code/index.txt +++ b/docs/internals/contributing/writing-code/index.txt @@ -1,43 +1,51 @@ -============ -Writing code -============ +================= +Contributing code +================= -So you'd like to write some code to improve Django? Awesome! There are several -ways you can help Django's development: +So you'd like to write some code, documentation or tests to improve Django? +There are several ways you can help Django's development. -* :doc:`Report bugs <../bugs-and-features>` in our `ticket tracker`_. +Tutorials +========= -* Join the |django-developers| mailing list and share your ideas for how to - improve Django. We're always open to suggestions. You can also interact on - the `Django forum`_ and the `#django-dev IRC channel`_. +The Django tutorial contains a whole section that walks you step-by-step +through the contributing code process. -* :doc:`Submit patches ` for new and/or fixed behavior. If - you're looking for a way to get started contributing to Django read the - :doc:`/intro/contributing` tutorial and have a look at the `easy pickings`_ - tickets. The :ref:`patch-review-checklist` will also be helpful. +.. toctree:: + :maxdepth: 1 -* :doc:`Improve the documentation <../writing-documentation>` or :doc:`write - unit tests `. + /intro/contributing -* :doc:`Triage tickets and review patches <../triaging-tickets>` created by - other users. +How-to guides +============= -* Read the :doc:`../new-contributors` to help you get orientated in the - development process. +If you already have some familiarity with the processes and principles, +our documentation also contains useful guidance on specific topics: -Browse the following sections to find out how to give your code patches the -best chances to be included in Django core: +.. toctree:: + :maxdepth: 1 + + How to submit a patch to Django for new and/or fixed behavior + How to write and run tests + How to run Django's unit tests + How to work with Git and GitHub + +Related topics +============== + +It's important to understand how we work and the conventions we adopt. .. toctree:: :maxdepth: 1 coding-style - unit-tests - submitting-patches - working-with-git javascript + ../committing-code + +We maintain a curated list of small issues suited to first-time or less +experienced contributors, using the "easy pickings" filter. These are strongly +recommended for those contributors looking to make a contribution. + +* Browse `easy pickings`_ tickets. -.. _ticket tracker: https://code.djangoproject.com/ .. _easy pickings: https://code.djangoproject.com/query?status=!closed&easy=1 -.. _#django-dev IRC channel: https://web.libera.chat/#django-dev -.. _Django forum: https://forum.djangoproject.com/ diff --git a/docs/internals/contributing/writing-code/javascript.txt b/docs/internals/contributing/writing-code/javascript.txt index 657cc66ded3..25165206f07 100644 --- a/docs/internals/contributing/writing-code/javascript.txt +++ b/docs/internals/contributing/writing-code/javascript.txt @@ -1,6 +1,6 @@ -========== -JavaScript -========== +=============== +JavaScript code +=============== While most of Django core is Python, the ``admin`` and ``gis`` contrib apps contain JavaScript code.