apply my comments

doc/rtd/development/code_review.rst

@@ -25,8 +25,9 @@ Cloud-init contributors, community members and users are encouraged to ask for
 help if they need it. If you have questions about the code review process, or
 need advice on an open PR, these are the available avenues:
 
-* on an open PR, leave a comment on that PR,
+* Open a PR, add "WIP:" to the title, and leave a comment on that PR
 * join the ``#cloud-init`` `channel on the Libera IRC <IRC_>`_ network
+* post on the ``#cloud-init`` `Discourse topic <Discourse_>`_
 * send an email to the cloud-init mailing list: ::
 
     [email protected]
@@ -132,30 +133,16 @@ There are three potential outcomes: **merged**, **rejected permanently**, and
 the :ref:`inactive pull requests<inactive-PRs>` section for details about
 temporary closure.
 
-In this section, we use the verbs "merge" or "squash merge" to mean "squash
-merged using the GitHub UI", which is the only way that changes can land in
-cloud-init's ``main`` branch.
-
 A committer is assigned
 -----------------------
 
-The committers, as a team, assign a committer to the PR. This committer is
+The committers assign a committer to the PR. This committer is
 expected to shepherd the PR to completion (and to merge it, if that is the
 outcome reached).
 
 They perform an initial review, and monitor the PR to ensure the proposer is
 receiving help if they need it. The committers perform this assignment on a
-daily basis for any new PRs submitted.
-
-This assignment gives the proposer a clear point of contact with a cloud-init
-core developer, and ensures that they get timely feedback on their PR. It does
-not imply that the committer has ownership over the review process, or that
-they are the only person who can review the PR. Any other reviewers should feel
-free to add their comments and suggestions as they wish.
-
-The assigned committer can delegate the code review of a PR to another reviewer
-if they think that person would be better suited. In GitHub terms, this is
-setting an **Assignee**, not requesting a review.
+regular basis for any new PRs submitted.
 
 Committer's initial review
 --------------------------

doc/rtd/development/contribute_docs.rst

@@ -55,8 +55,8 @@ You will need to add your GitHub username (alphabetically) to the in-repository
 list that we use to track :ref:`CLA signatures <contributing-prerequisites>`:
 `tools/.github-cla-signers`_.
 
-This needs to be included alongside your first contribution: we cannot merge a
-PR that only adds your name to the CLA.
+Please include this in the same PR alongside your first contribution. Do
+not create a separate PR to add your name to the CLA signatures.
 
 If you need some help with your contribution, you can contact us on our
 `IRC channel <IRC_>`_. If you have already submitted a work-in-progress PR, you

doc/rtd/development/dir_layout.rst

@@ -3,36 +3,6 @@
 Directory layout
 ****************
 
-Cloud-init's directory structure is somewhat different from a regular
-application: ::
-
-  /var/lib/cloud/
-      - data/
-         - instance-id
-         - previous-instance-id
-         - datasource
-         - previous-datasource
-         - previous-hostname
-      - handlers/
-      - instance
-      - instances/
-          i-00000XYZ/
-            - boot-finished
-            - cloud-config.txt
-            - datasource
-            - handlers/
-            - obj.pkl
-            - scripts/
-            - sem/
-            - user-data.txt
-            - user-data.txt.i
-      - scripts/
-         - per-boot/
-         - per-instance/
-         - per-once/
-      - seed/
-      - sem/
-
 ``/var/lib/cloud``
 ==================
 

doc/rtd/development/docs_layout.rst

@@ -36,6 +36,9 @@ directory:
 ``man/``
 ========
 
+This subdirectory contains the Linux man pages for the binaries provided
+by cloud-init.
+
 
 ``rtd/``
 ========
@@ -68,6 +71,9 @@ can be found in this folder.
 ``sources/``
 ============
 
+This subdirectory contains demos which can help the reader understand
+how parts of the product work.
+
 .. LINKS
 
 .. include:: ../links.txt

doc/rtd/development/find_issues.rst

@@ -18,26 +18,24 @@ Claiming an issue
 You can express your interest in an issue by posting a comment on it. You
 should only work on one open issue at a time to avoid overloading yourself.
 
-If you have not submitted a PR (or a draft/"work-in-progress" PR) within a few
-days of leaving your comment, other contributors should consider the issue to
-be available for them to work on.
+If you have not submitted a PR or commented with an updated status within a
+week of leaving your initial comment, other contributors should consider the
+issue to be available for them to work on.
 
 When you submit your proposed fix for an issue, including the issue number in
 the PR commit message will link the issue to your proposed fix. This is the
 ``Fixes GH-0000`` line in the template PR commit message.
 
-We will only assign an issue if there is a PR in progress.
-
 Creating an issue
 =================
 
 If you've spotted something that doesn't already have an issue, you can always
 create one in GitHub.
 
-You can also submit an issue in GitHub through the documentation using the
-"Give feedback" button at the top of each page. It will automatically include
-the URL of the page you came from, so all you need to do is describe the issue
-you've found.
+For documentation issues, you can submit an issue in GitHub using the
+"Give feedback" button at the top of each documentation page. It will
+automatically include the URL of the page you came from, so all you need to
+do is describe the issue you've found.
 
 No-code or low-code options
 ===========================

doc/rtd/development/first_PR.rst

@@ -1,7 +1,14 @@
 Submit your first pull request
 ******************************
 
-Follow these steps to submit your first pull request to cloud-init:
+Follow these steps prior to submitting  your first pull request to cloud-init:
+
+Setup Git and GitHub appropriately
+==================================
+
+Understanding how to use Git and GitHub is a prerequisite for contributing to
+cloud-init. Please refer to the `GitHub quickstart`_ documentation
+for more information.
 
 Sign the CLA
 ============
@@ -28,131 +35,38 @@ For any questions or help with the process, email
 "Cloud-init CLA". You can also contact user ``falcojr`` in the #cloud-init
 channel on the `Libera IRC network <IRC_>`_.
 
-Configure git
-=============
-
-Next, configure ``git`` with your email and name for commit messages.
-
-Your name will appear in commit messages and will also be used in changelogs or
-release notes. Give yourself credit! ::
-
-  git config user.name "Your Name"
-  git config user.email "Your Email"
-
-Clone the repository
-====================
-
-* Sign in to your `GitHub`_ account.
-
-* From the cloud-init `upstream repository <GH repo_>`_ on GitHub, click on the
-  :guilabel:`Fork` button.
-
-* Create a new remote pointing to your personal GitHub repository.
-
-  .. code-block:: sh
-
-      git clone [email protected]:GH_USER/cloud-init.git
-      cd cloud-init
-      git remote add upstream [email protected]:canonical/cloud-init.git
-      git push origin main
-
-  Remember to change ``GH_USER`` to your GitHub username.
-
-Work on your feature or bug
-===========================
+Add your name to the CLA signers list
+=====================================
 
-Create a new topic branch for your work: ::
+As part of your first PR to cloud-init, you should also add your GitHub
+username (alphabetically) to the in-repository list that we use to track CLA
+signatures: `tools/.github-cla-signers`_.
 
-    git checkout -b my-topic-branch
+`PR #344`_ and `PR #345`_ are good examples of what this should look like in
+your pull request, though please do not use a separate PR for this step.
 
-Create a virtual environment
-----------------------------
+Create a sandbox environment
+============================
 
 It is very often helpful to create a safe and sandboxed environment to test
 your changes in while you work. If you are not sure how to do this, check out
 :ref:`our QEMU tutorial<tutorial_qemu>`, which walks through this process
 step-by-step.
 
-Make your commits
------------------
-
-Make and commit your changes (note, you can make multiple commits, fixes, and
-add more commits): ::
-
-    git commit
-
-Add your name to the CLA signers list
--------------------------------------
-
-As part of your first PR to cloud-init, you should also add your GitHub
-username (alphabetically) to the in-repository list that we use to track CLA
-signatures: `tools/.github-cla-signers`_.
-
-`PR #344`_ and `PR #345`_ are good examples of what this should look like in
-your pull request.
-
 Format the code
----------------
+===============
 
 Apply the ``black`` and ``isort`` formatting rules with `tox`_: ::
 
     tox -e do_format
 
 Run unit tests
---------------
+==============
 
 Run unit tests and lint/formatting checks with `tox`_: ::
 
     tox
 
-Push your changes
------------------
-
-Push your changes to your personal GitHub repository: ::
-
-    git push -u origin my-topic-branch
-
-Create a pull request
-=====================
-
-Use your browser to create a pull request:
-
-- Open the branch on GitHub
-
-- You can see a web view of your repository and navigate to the branch at: ::
-
-      https://github.com/GH_USER/cloud-init/tree/my-topic-branch
-
-- Click :guilabel:`Pull Request`.
-
-- Fill out the pull request title, summarizing the change and a longer message
-  indicating important details about the changes included, like:
-
-  .. code-block:: text
-
-     Activate the frobnicator.
-
-     The frobnicator was previously inactive and now runs by default.
-     This may save the world some day. Then, list the bugs you fixed
-     as footers with syntax as shown here.
-
-     The commit message should be one summary line of less than
-     70 characters followed by a blank line, and then one or more
-     paragraphs wrapped at 72 characters describing the change and why
-     it was needed.
-
-     This is the message that will be used on the commit when it
-     is squashed and merged into main. If there is a related launchpad
-     bug, specify it at the bottom of the commit message.
-
-     LP: #NNNNNNN (replace with the appropriate bug reference or remove this line entirely if there is no associated Launchpad bug)
-     Fixes GH-00000 (replace with the appropriate GitHub issue number or remove this line if there's no associated GitHub issue)
-
-  Note that the project continues to use LP: #NNNNN format for closing
-  Launchpad bugs rather than GitHub Issues.
-
-- Click :guilabel:`Create Pull Request`
-
 Read our code review process
 ============================
 
@@ -161,11 +75,7 @@ cloud-init :ref:`Code Review Process<code_review_process>`, so you can
 understand how your changes will end up in cloud-init's codebase.
 
 .. include:: ../links.txt
-.. _quickstart documentation: https://docs.github.com/en/get-started/quickstart
 .. _tools/.github-cla-signers: https://github.com/canonical/cloud-init/blob/main/tools/.github-cla-signers
-.. _repository: https://github.com/canonical/cloud-init
 .. _contributor-agreement-canonical: https://launchpad.net/%7Econtributor-agreement-canonical/+members
 .. _PR #344: https://github.com/canonical/cloud-init/pull/344
 .. _PR #345: https://github.com/canonical/cloud-init/pull/345
-.. _PEP-484: https://www.python.org/dev/peps/pep-0484/
-.. _PEP-526: https://www.python.org/dev/peps/pep-0526/

doc/rtd/development/index.rst

@@ -49,8 +49,8 @@ Getting started
     first_PR.rst
     code_review.rst
 
-For existing contributors
-=========================
+Contribute
+==========
 
 Pull request checklist
 ----------------------
@@ -62,7 +62,7 @@ Before any pull request can be accepted, remember to do the following:
 * Add or update any :ref:`unit tests<testing>` accordingly.
 * Add or update any :ref:`integration_tests` (if applicable).
 * Format code (using ``black`` and ``isort``) with ``tox -e do_format``.
-* Run unit tests and/or linting checks pass using ``tox``.
+* Ensure unit tests and/or linting checks pass using ``tox``.
 * Submit a PR against the ``main`` branch of the cloud-init repository.
 
 Debugging and reporting
@@ -75,28 +75,6 @@ Debugging and reporting
    logging.rst
    debugging.rst
 
-Transferring CLA Signatures from Launchpad to GitHub
-----------------------------------------------------
-
-If you signed the CLA in Launchpad before the GitHub username field was
-included, we need to verify the link between your `Launchpad`_ account and
-your `GitHub`_ account. To enable us to do this, we ask that you create a
-branch with both your Launchpad and GitHub usernames against both the Launchpad
-and GitHub cloud-init repositories. We've added a tool
-(``tools/migrate-lp-user-to-github``) to the cloud-init repository to handle
-this migration as automatically as possible.
-
-The cloud-init team will review the two merge proposals, verify that the
-CLA has been signed for the Launchpad user, and record the associated GitHub
-account.
-
-.. note::
-
-   If you are a first time contributor, you will not need to do this. All new
-   CLA signatures are handled as part of the GitHub pull request process when
-   you make your first pull request.
-
-
 .. LINKS:
 .. include:: ../links.txt
 .. _quickstart documentation: https://docs.github.com/en/get-started/quickstart

doc/rtd/development/style_docs.rst

@@ -109,7 +109,7 @@ Common words
 
 There are some common words that should follow specific usage in text:
 
-- **Cloud-init**: Always hyphenated, and follows sentence case, so only
+- **cloud-init**: Always hyphenated, and follows sentence case, so only
   capitalised at the start of a sentence.
 - **metadata**, **datasource**: One word.
 - **user data**, **vendor data**: Two words, not to be combined or hyphenated.

doc/rtd/links.txt

@@ -9,3 +9,5 @@
 .. _Launchpad: https://launchpad.net
 .. _the docs: https://cloudinit.readthedocs.io/en/latest/
 .. _tox: https://tox.readthedocs.io/en/latest/
+.. _Discourse: https://discourse.ubuntu.com/c/server/cloud-init/54
+.. _Github quickstart: https://docs.github.com/en/get-started/quickstart