From 1d8601ea58192c345d61aae40c7e58d248107875 Mon Sep 17 00:00:00 2001 From: delucchi-cmu Date: Wed, 14 Feb 2024 12:24:00 -0500 Subject: [PATCH] Create a configuration checklist with references. --- README.md | 2 +- copier.yml | 3 ++ docs/conf.py | 6 ++- docs/index.rst | 3 +- docs/source/configuration_checklist.rst | 67 +++++++++++++++++++++++++ docs/source/new_project.rst | 39 ++------------ docs/source/overview.rst | 1 + 7 files changed, 83 insertions(+), 38 deletions(-) create mode 100644 docs/source/configuration_checklist.rst diff --git a/README.md b/README.md index cb1e4f18..0898a25b 100644 --- a/README.md +++ b/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/) diff --git a/copier.yml b/copier.yml index 12cbea1a..56780121 100644 --- a/copier.yml +++ b/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. ### diff --git a/docs/conf.py b/docs/conf.py index 1334111b..67d3ef8e 100644 --- a/docs/conf.py +++ b/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 diff --git a/docs/index.rst b/docs/index.rst index f694912f..cf64b0c6 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/source/configuration_checklist.rst b/docs/source/configuration_checklist.rst new file mode 100644 index 00000000..3215b33a --- /dev/null +++ b/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 `_ + * 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 `_ + * 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 `_ + * 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 ` +- :ref:`Set up smoke test email notifications ` +- :ref:`Set up smoke test slack notifications ` +- :ref:`Set up code coverage with codecov ` +- :ref:`Set up a PyPI package ` +- :ref:`Set up a conda-forge package ` +- :ref:`Connect your project to ReadTheDocs ` + +Still have questions? +------------------------------------------------------------------------------- + +:doc:`/source/contact` \ No newline at end of file diff --git a/docs/source/new_project.rst b/docs/source/new_project.rst index 2e2615ce..b272d10d 100644 --- a/docs/source/new_project.rst +++ b/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 `_ - * 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 `_ - * 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 `_ - * 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` Still have questions? ------------------------------------------------------------------------------- diff --git a/docs/source/overview.rst b/docs/source/overview.rst index 65b98c71..49e533f7 100644 --- a/docs/source/overview.rst +++ b/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` +* :doc:`Configure a new project` * :doc:`Upgrade an existing project` \ No newline at end of file