From 5cac44be06c29929acb02771ef440eb4719e5312 Mon Sep 17 00:00:00 2001 From: David Rosa Date: Wed, 27 Jul 2022 11:54:05 -0400 Subject: [PATCH] docs: Reorganize sections and pages about contributing to Zulip. We should rearrange Zulip's developer docs to make it easier to find the documentation that new contributors need. Name changes Rename "Code contribution guide" section -> "Contributing to Zulip". Rename "Contributing to Zulip" page -> "Contributing guide". Organizational changes to the newly-named "Contributing to Zulip": Move up "Contributing to Zulip", as the third link in sidebar index. Move up renamed "Contributing guide" page to the top of this section. Move up "Zulip code of Conduct", as the second link of this section. Move down "Licensing", as the last link of this section. Move "Accessibility" just below "HTML and CSS" in Subsystems section. Update all links according to the changes above. Redirects should be added as needed. Fixes: #22517. --- CONTRIBUTING.md | 8 +++--- .../contributing.md | 0 docs/contributing/gsoc.md | 6 ++--- docs/contributing/index.md | 8 +++--- docs/index.md | 27 +++++++++---------- docs/overview/index.md | 1 - docs/overview/release-lifecycle.md | 2 +- docs/production/upgrade-or-modify.md | 2 +- .../accessibility.md | 0 docs/subsystems/index.md | 1 + templates/zerver/help/high-contrast-mode.md | 2 +- tools/linter_lib/custom_check.py | 2 +- 12 files changed, 29 insertions(+), 30 deletions(-) rename docs/{overview => contributing}/contributing.md (100%) rename docs/{contributing => subsystems}/accessibility.md (100%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f82ca1e5ba..aab46a6289 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Contributing to Zulip +# Contributing guide Welcome to the Zulip community! @@ -184,7 +184,7 @@ stream](https://chat.zulip.org/#narrow/stream/101-design) in the [Zulip development community](https://zulip.com/development-community/) For more advice, see [What makes a great Zulip -contributor?](https://zulip.readthedocs.io/en/latest/overview/contributing.html#what-makes-a-great-zulip-contributor) +contributor?](#what-makes-a-great-zulip-contributor) below. ### Submitting a pull request @@ -267,7 +267,7 @@ The key to keeping your review moving through the review process is to: - Make it as easy as possible to review the changes you made. In order to do this, when you believe you have addressed the previous round of -feedback on your PR as best you can, post an comment asking reviewers to take +feedback on your PR as best you can, post a comment asking reviewers to take another look. Your comment should make it easy to understand what has been done and what remains by: @@ -314,7 +314,7 @@ labels. on [Git commit discipline](https://zulip.readthedocs.io/en/latest/contributing/version-control.html#commit-discipline). 2. If all the feedback has been addressed, did you [leave a - comment](https://zulip.readthedocs.io/en/latest/overview/contributing.html#how-to-help-move-the-review-process-forward) + comment](#how-to-help-move-the-review-process-forward) explaining that you have done so and **requesting another review**? If not, it may not be clear to project maintainers or reviewers that your PR is ready for another look. diff --git a/docs/overview/contributing.md b/docs/contributing/contributing.md similarity index 100% rename from docs/overview/contributing.md rename to docs/contributing/contributing.md diff --git a/docs/contributing/gsoc.md b/docs/contributing/gsoc.md index e2f1a5c734..31703c8cd0 100644 --- a/docs/contributing/gsoc.md +++ b/docs/contributing/gsoc.md @@ -67,7 +67,7 @@ also give you a feel for what it's like to do GSoC with us. We have an easy-to-set-up development environment, and a library of tasks that are great for first-time contributors. Use -[our first-time Zulip developer guide](../overview/contributing.md#your-first-codebase-contribution) +[our first-time Zulip developer guide](contributing.md#your-first-codebase-contribution) to get your Zulip development environment set up and to find your first issue. If you have any trouble, please speak up in the [#GSoC](https://chat.zulip.org/#narrow/stream/14-GSoC) stream on the @@ -135,7 +135,7 @@ For the first time in 2022, being a student is not required in order to apply to GSoC. We are happy to accept both student and non-student participants. Our documentation on [what makes a great Zulip -contributor](../overview/contributing.md#what-makes-a-great-zulip-contributor) +contributor](contributing.md#what-makes-a-great-zulip-contributor) offers some additional helpful information. We also recommend reviewing the [official GSoC resources](https://developers.google.com/open-source/gsoc/resources/), @@ -169,7 +169,7 @@ other contributors learn from reading the conversation. - [Try, Then Ask](https://www.mattringel.com/2013/09/30/you-must-try-and-then-you-must-ask/) - [We Aren’t Just Making Code, We’re Making History](https://www.harihareswara.net/sumana/2016/10/12/0) - [How to Ask Good Questions](https://jvns.ca/blog/good-questions/) -- Understand [what makes a great Zulip contributor](../overview/contributing.md#what-makes-a-great-zulip-contributor) +- Understand [what makes a great Zulip contributor](contributing.md#what-makes-a-great-zulip-contributor) This is a typical question/response sequence: diff --git a/docs/contributing/index.md b/docs/contributing/index.md index f7c433015b..daaa94a29d 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -1,18 +1,18 @@ -# Code contribution guide +# Contributing to Zulip ```{toctree} --- maxdepth: 3 --- +contributing +../code-of-conduct version-control code-style code-reviewing zulipbot-usage -accessibility -licensing bug-reports -../code-of-conduct gsoc summer-with-zulip +licensing ``` diff --git a/docs/index.md b/docs/index.md index d19db168b9..ba04439aff 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,7 +8,7 @@ Welcome! Zulip's documentation is split into four parts: installing and maintaining a production self-hosted Zulip installation. - [API documentation](https://zulip.com/api/), for writing integrations or bots using the Zulip API. -- [Contributor documentation](overview/contributing.md), for +- [Contributor documentation](contributing/contributing.md), for developing the Zulip software, translating, submitting bug reports, or making other contributions to the project. @@ -20,17 +20,16 @@ the Zulip project and its features can be found at This site contains our installation and contributor documentation. If this is your first time here, you may want to start with [Production -installation](production/install.md) or [Contributing to -Zulip](overview/contributing.md). +installation](production/install.md) or [Contributing guide](contributing/contributing.md). Contents: - {ref}`Overview ` - {ref}`Zulip in production ` +- {ref}`Contributing to Zulip ` - {ref}`Development environment ` - {ref}`Developer tutorials ` - {ref}`Git guide ` -- {ref}`Code contribution guide ` - {ref}`Code testing ` - {ref}`Subsystem documentation ` - {ref}`Writing documentation ` @@ -56,6 +55,16 @@ maxdepth: 3 production/index ``` +(contributing-to-zulip)= + +```{toctree} +--- +maxdepth: 3 +--- + +contributing/index +``` + (development-environment)= ```{toctree} @@ -86,16 +95,6 @@ maxdepth: 3 git/index ``` -(code-contribution-guide)= - -```{toctree} ---- -maxdepth: 3 ---- - -contributing/index -``` - (code-testing)= ```{toctree} diff --git a/docs/overview/index.md b/docs/overview/index.md index 91233c9403..0f2b730ed1 100644 --- a/docs/overview/index.md +++ b/docs/overview/index.md @@ -6,7 +6,6 @@ maxdepth: 3 --- readme -contributing architecture-overview directory-structure release-lifecycle diff --git a/docs/overview/release-lifecycle.md b/docs/overview/release-lifecycle.md index 2ee950ecc5..961a900c26 100644 --- a/docs/overview/release-lifecycle.md +++ b/docs/overview/release-lifecycle.md @@ -184,7 +184,7 @@ GitHub issue. Please an include an explanation of your use case: such details can be extremely helpful in designing appropriately general solutions, and also helps us identify cases where an existing solution can solve your problem. See [Reporting -issues](contributing.md#reporting-issues) for more details. +issues](../contributing/contributing.md#reporting-issues) for more details. ## Client apps diff --git a/docs/production/upgrade-or-modify.md b/docs/production/upgrade-or-modify.md index c10cb7b103..b8186846cb 100644 --- a/docs/production/upgrade-or-modify.md +++ b/docs/production/upgrade-or-modify.md @@ -822,7 +822,7 @@ upgrading to `main`, make sure you understand: Zulip contains thousands of changes submitted by volunteer contributors like you. If your changes are likely to be of useful to other organizations, consider [contributing -them](../overview/contributing.md). +them](../contributing/contributing.md). [fork-clone]: ../git/cloning.md#get-zulip-code [upgrade-zulip-from-git]: #upgrading-from-a-git-repository diff --git a/docs/contributing/accessibility.md b/docs/subsystems/accessibility.md similarity index 100% rename from docs/contributing/accessibility.md rename to docs/subsystems/accessibility.md diff --git a/docs/subsystems/index.md b/docs/subsystems/index.md index fa67863832..7ae795eb5f 100644 --- a/docs/subsystems/index.md +++ b/docs/subsystems/index.md @@ -8,6 +8,7 @@ maxdepth: 3 dependencies settings html-css +accessibility events-system sending-messages notifications diff --git a/templates/zerver/help/high-contrast-mode.md b/templates/zerver/help/high-contrast-mode.md index dbf55a8f09..bbaeb4d1cb 100644 --- a/templates/zerver/help/high-contrast-mode.md +++ b/templates/zerver/help/high-contrast-mode.md @@ -11,4 +11,4 @@ W3C's Web Content Accessibility Guidelines. ## Related articles -* [Accessibility in Zulip](https://zulip.readthedocs.io/en/latest/contributing/accessibility.html) +* [Accessibility in Zulip](https://zulip.readthedocs.io/en/latest/subsystems/accessibility.html) diff --git a/tools/linter_lib/custom_check.py b/tools/linter_lib/custom_check.py index a6952d0b0e..17a358c573 100644 --- a/tools/linter_lib/custom_check.py +++ b/tools/linter_lib/custom_check.py @@ -847,7 +847,7 @@ markdown_rules = RuleList( { "pattern": "https://zulip.readthedocs.io/en/latest/[a-zA-Z0-9]", "exclude": { - "docs/overview/contributing.md", + "docs/contributing/contributing.md", "docs/overview/readme.md", "docs/README.md", "docs/subsystems/email.md",