Create a configuration checklist with references. (#428)

Author: delucchi-cmu

README.md

@@ -7,7 +7,7 @@ This project template codifies LINCC-Framework's best practices for python code
 
 [Copier](https://copier.readthedocs.io/en/latest/) is required to use this template. Copier is an open source tool that hydrates projects from templates and natively supports updating projects as the original template matures. It's really neat!
 
-Our template works best with Copier v8.0 and above. 
+Our template works best with Copier v9.1 and above. 
 For all the information, see the detailed user guide in
 [readthedocs](https://lincc-ppt.readthedocs.io/)
 

copier.yml

@@ -187,6 +187,9 @@ _message_after_copy: |
        - Enable dependabot in github
        - Add another GitHub user as an administrator on the repository
 
+    These steps are detailed at
+        https://lincc-ppt.readthedocs.io/en/latest/source/configuration_checklist.html
+
 ###
 # Below this line are Copier configuration options.
 ###

docs/conf.py

@@ -27,7 +27,7 @@
 html_static_path = ["static"]
 html_css_files = ["custom.css"]
 
-extensions = ["sphinx_copybutton"]
+extensions = ["sphinx_copybutton", "sphinx.ext.autosectionlabel"]
 
 # -- sphinx-copybutton configuration ----------------------------------------
 ## sets up the expected prompt text from console blocks, and excludes it from
@@ -38,6 +38,10 @@
 ## lets us suppress the copy button on select code blocks.
 copybutton_selector = "div:not(.no-copybutton) > div.highlight > pre"
 
+# -- Options for autosectionlabel -------------------------------------------------
+
+autosectionlabel_prefix_document=True
+
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 

docs/index.rst

@@ -12,7 +12,7 @@ If you find it useful, or have any questions or concerns when using the template
 please :doc:`/source/contact`
 
 .. important:: 
-   These instructions assume you are using ``copier`` version 8.0 or newer. Some
+   These instructions assume you are using ``copier`` version 9.1 or newer. Some
    features may not be available in older versions.
 
 .. toctree::
@@ -21,6 +21,7 @@ please :doc:`/source/contact`
 
    source/overview
    source/new_project
+   source/configuration_checklist
    source/update_project
    source/existing_project
    source/contributing

docs/source/configuration_checklist.rst

@@ -0,0 +1,67 @@
+Configuring a new project
+===============================================================================
+
+So you've created a new python project from the template! Great!
+
+Now let's get other services linked up to your new project to make the most of
+what the template and open source CI has to offer!
+
+Configure your GitHub repository for safety and security
+-------------------------------------------------------------------------------
+
+* Consider setting up branch protection rules.
+
+  * `GitHub Instructions for protected branches <https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-pull-request-reviews-before-merging>`_
+  * This will help ensure your code is always ready to deploy by running all tests
+    pass to merging into the ``main`` branch.
+
+* Enable ``dependabot`` for your new repository
+
+  * `GitHub Instructions for dependabot <https://docs.github.com/en/code-security/getting-started/securing-your-repository#managing-dependabot-security-updates>`_
+  * There are several different features that ``dependabot`` offers to keep your dependencies
+    up to date and your code secure. It's as easy as clicking a checkbox to get started.
+
+* Add another GitHub user as an administrator on your repository
+
+  * `GitHub Instructions for repo access <https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-teams-and-people-with-access-to-your-repository>`_
+  * It's just a good idea - like having a spare set of keys for your Lamborghini.
+
+Configure your GitHub repository for convenience
+-------------------------------------------------------------------------------
+
+There are several convenient options in GitHub that are not enabled by default.
+We find ourselves setting these options on all our development repositories, and 
+list them here for reference.
+
+In your repo, "Settings" tab, "General" page, scroll down to the "Pull Requests" 
+section:
+
+* Check **"Allow squash merging"**. This lets you combine several intermediate
+  commits on a development branch into a single merge into main. The merge
+  history will stay cleaner.
+* Check **"Allow auto-merge"**. This lets you set a pull request to automatically
+  merge when all required reviews and status criteria is met. This can be
+  great when working with folks in other time zones - you don't need to be 
+  around to merge your change once it's ready.
+* Check **"Automatically delete head branches"**. If you're working in development
+  branches and only merging in to main with pull requests (which you should do!), 
+  your repo may quickly fill up with stale development branches. With
+  this feature enabled, your development branches will be automatically deleted
+  once the pull requests are merged into main.
+
+
+Get the most out of this template
+-------------------------------------------------------------------------------
+
+- :ref:`Finish setting up benchmarks <practices/ci_benchmarking:Set-up>`
+- :ref:`Set up smoke test email notifications <practices/ci_testing:Email notifications>`
+- :ref:`Set up smoke test slack notifications <practices/ci_testing:Slack notifications>`
+- :ref:`Set up code coverage with codecov <practices/code_coverage:How to manage>`
+- :ref:`Set up a PyPI package <practices/pypi:Set-up>`
+- :ref:`Set up a conda-forge package <practices/conda:Set-up>`
+- :ref:`Connect your project to ReadTheDocs <practices/sphinx:How to get started with ReadTheDocs>`
+
+Still have questions?
+-------------------------------------------------------------------------------
+
+:doc:`/source/contact`

docs/source/new_project.rst

@@ -43,7 +43,7 @@ questions:
        code (``src/{{package_name}}``). The package name must start with a lowercase letter, 
        followed by one or more of the following (a-z, 0-9, _).
    * - *What github organization will your project live under?*
-     - This will either be a gihub organization, or your github username, if you're working outside 
+     - This will either be a github organization, or your github username, if you're working outside 
        of an organization. This is used to construct URLs to your project, like
        ``https://github.com/{{project_organization}}/{{project_name}}``
    * - *What is the name of the code author?* 
@@ -169,41 +169,10 @@ Notice that when you create a PR in GitHub, a set of tests for Continuous
 Integration starts up to verify that the project can build successfully and 
 that all the unit tests pass. Neato!
 
+Next steps
+-------------------------------------------------------------------------------
 
-Additional configurations
--------------------------
-
-Configure your GitHub repository for safety and security
-********************************************************
-
-* Consider setting up branch protection rules.
-
-  * `GitHub Instructions for protected branches <https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-pull-request-reviews-before-merging>`_
-  * This will help ensure your code is always ready to deploy by running all tests
-    pass to merging into the ``main`` branch.
-
-* Enable ``dependabot`` for your new repository
-
-  * `GitHub Instructions for dependabot <https://docs.github.com/en/code-security/getting-started/securing-your-repository#managing-dependabot-security-updates>`_
-  * There are several different features that ``dependabot`` offers to keep your dependencies
-    up to date and your code secure. It's as easy as clicking a checkbox to get started.
-
-* Add another GitHub user as an administrator on your repository
-
-  * `GitHub Instructions for repo access <https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-teams-and-people-with-access-to-your-repository>`_
-  * It's just a good idea - like having a spare set of keys for your Lamborghini.
-
-Get the most out of this template
-*********************************
-At this point, your new project is hydrated, version controlled and ready for
-you to start coding. But there's a lot more that this template has to offer!
-
-If you want to enable performance benchmarking there are some additional steps. 
-Refer to the "How to manage" section of :doc:`Continuous Integration Benchmarking <../practices/ci_benchmarking>`
-for more information.
-
-Finally, take a look at the :doc:`Best Practices section <../practices/overview>` to learn about
-built in pre-commit hooks, GitHub CI, automatic documentation, and more.
+:doc:`Configure a new project<configuration_checklist>`
 
 Still have questions?
 -------------------------------------------------------------------------------

docs/source/overview.rst

@@ -73,4 +73,5 @@ Given that your system satisfies the requirements, go ahead and install Copier.
 Now choose your next adventure...
 -------------------------------------
 * :doc:`Start a new project<new_project>`
+* :doc:`Configure a new project<configuration_checklist>`
 * :doc:`Upgrade an existing project<existing_project>`