From 6e7c3d26c5b922dd784cc8a8315d501d91db02cb Mon Sep 17 00:00:00 2001 From: Toon Verstraelen Date: Wed, 19 Jun 2024 11:30:57 +0200 Subject: [PATCH 1/4] Maintainer Guide framework --- CONTRIBUTING.md | 2 +- MAINTAINING.md | 39 ++++++++++++ README.md | 4 +- contributing/config.md | 2 +- contributing/workflow.md | 2 +- maintaining/minimal.md | 129 +++++++++++++++++++++++++++++++++++++++ 6 files changed, 174 insertions(+), 4 deletions(-) create mode 100644 MAINTAINING.md create mode 100644 maintaining/minimal.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9f156b8..9d82374 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# QC-Devs Contributing Guidelines +# QC-Devs Contributor Guide Welcome to the **QC-Devs** community! We are excited to have you here. diff --git a/MAINTAINING.md b/MAINTAINING.md new file mode 100644 index 0000000..ec212ac --- /dev/null +++ b/MAINTAINING.md @@ -0,0 +1,39 @@ +# QC-Devs Maintainer Guide + +## Introduction + +This document discusses our default repository setup. +It can be used as a set of step-by-step instructions for starting a new repository +or upgrading an existing one. +The goal is to achieve more consistency across all QC-Devs projects, +and to provide tools to make your repository welcoming to contributions +in a way that is consistent with our +[Contributor Guide](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md). + +This guide is a modular collection of mini-tutorials +for setting up your repository and learning best practices. +As with all of our work, contributions to this document are welcome. + +## Repository setup + +1. The [Minimal Initial Repository](maintaining/minimal.md) walks you through the first steps + of setting up a Git repository (locally and on GitHub) + and adding a few files that should always be present. + +2. Python package + - Setup tools (TODO) + - Recommended Packages to facilitate developemnt (TODO) + +3. Documentation + - Changelogs (TODO) + - Sphinkx (TODO) + - Jupyter Book (TODO) + +4. Continuous integration + - Pre-commit (TODO) + - Unit testing (TODO) + - Code coverage (TODO) + - Documentation build and deployment (TODO) + - Deployment on PyPI (TODO) + - Deepsource analysis (TODO) + - Sourcery AI pull request review (TODO) diff --git a/README.md b/README.md index 66ff766..d349e06 100644 --- a/README.md +++ b/README.md @@ -16,9 +16,11 @@ GitGub documentation for this repository: - The [Code of Conduct](CODE_OF_CONDUCT.md) establishes our expectations of everyone who participates in QC-Devs, in order to make it a stimulating and enjoyable environment. -- The [Contributing Guide](CONTRIBUTING.md) +- The [Contributor Guide](CONTRIBUTING.md) documents how to contribute to one of the repositories. Each repository also provides additional details, such as file names and tools used. +- The [Maintainer Guide](MAINTAINING.md) + helps you set up and maintain a repository according to best practices. - The [GSoC Contributor Guide](GSoC.md) provides guidance for individuals interested in participating in the Google Summer of Code (GSoC) program with QC-Devs. diff --git a/contributing/config.md b/contributing/config.md index 41883ec..2192955 100644 --- a/contributing/config.md +++ b/contributing/config.md @@ -1,4 +1,4 @@ -# Git and GitHub configuration +# Git and GitHub Configuration - If you don't already have an SSH key pair, create one using the following terminal command: diff --git a/contributing/workflow.md b/contributing/workflow.md index 643d6fb..23533dc 100644 --- a/contributing/workflow.md +++ b/contributing/workflow.md @@ -28,7 +28,7 @@ Here, we will only go over the technicalities of creating a pull request. 3. Make changes to the source code. To make these easier to process and to maintain the code quality, general recommendations can be found in the - [Code Quality section of the main Contributing Guide](../CONTRIBUTING.md#code-quality). + [Code Quality section of the main Contributor Guide](../CONTRIBUTING.md#code-quality). 4. Verify that all the tests pass and that the documentation builds without warnings or errors. diff --git a/maintaining/minimal.md b/maintaining/minimal.md new file mode 100644 index 0000000..f347c19 --- /dev/null +++ b/maintaining/minimal.md @@ -0,0 +1,129 @@ +# Minimal Repository Setup + +If you have not already gone through the +[Git and GitHub Configuration for Contributors](../contributing/config.md), please do so first. +This guide builds further on that configuration. +It also assumes that you have [Git] and [pre-commit] installed. + +[Git]: https://git-scm.com/ +[pre-commit]: https://pre-commit.com/ + + +## Configure Your Local Git Software + +We use `main` as the default branch in our repositories. +This is configured with the following command + +```bash +git config --global init.defaultBranch main +``` + +## Create a Local Git Repository + +Run the following in your terminal: + +```bash +mkdir ${your-fancy-project-name} +cd ${your-fancy-project-name} +git init +``` + +where you replace `${your-fancy-project-name}` with the actual name of your repository. +Most GitHub projects use [kebab-case] for repository names. +(It's not clear why. My best guess is that weathered coders often suffer from [RSI] +and try to avoid the Shift key when they can. +It also looks cleaner.) + +[kebab-case]: https://stackoverflow.com/a/17820138/494584 +[RSI]: https://en.wikipedia.org/wiki/Repetitive_strain_injury + + +## Add a Few Essential Files + +The following files should always be present from the start: + +- `README.md` Markdown file containing: + + - A title with name of your project. + - A brief description. + - A statement that the documentation still needs to be written. + You will eventually replace this by a link to the documentation. + - References to our + [Contributor Guide](CONTRIBUTING.md) + and [Code of Conduct](CODE_OF_CONDUCT.md). + + For historical reasons, some projects use [ReStructuredText] instead of [Markdown]. + For new projects, we recommend using Markdown, + as it has better support in IDEs and documentation build tools. + +[ReStructuredText]: https://en.wikipedia.org/wiki/ReStructuredText +[Markdown]: https://en.wikipedia.org/wiki/Markdown + +- `LICENSE.txt`: + The open source license under which you publicly share your work. + See [Choose an open source license](https://choosealicense.com/) + Discuss this choice with your collaborators, supervisor, boss, etc. + It is an important decision, and changing it later can be hard + if others have already contributed under the terms of your original license. + +- `.editor-config`: + This file contains basic settings for source code editors and + is widely supported. + See [editorconfig.org](https://editorconfig.org/) for details. + Some examples: + + - https://github.com/theochem/iodata/blob/main/.editorconfig + - https://github.com/theochem/.github/blob/main/.editorconfig + +- `.gitignore` + This file lists all files that should never be included in the Git history. + In general, all temporary and output files should be listed here. + Some examples: + + - https://github.com/theochem/iodata/blob/main/.gitignore + - https://github.com/theochem/.github/blob/main/.gitignore + +- `.pre-commit-config.yaml`: + This file configures [pre-commit], which checks and cleans contributions *before* they are committed. + Some examples: + + - https://github.com/theochem/iodata/blob/main/.pre-commit-config.yaml + - https://github.com/theochem/.github/blob/main/.pre-commit-config.yaml + + More can be found in the [list of supported pre-commit hooks](https://pre-commit.com/hooks.html). + + Note that some of the tools listed in `.pre-commit-config.yaml` + rely on additional configuration settings, + most notably in `pyproject.toml`, which we'll cover later. + + +## Enable pre-commit on Your Repository + +Run the following command: + +```bash +pre-commit install +``` + +This command is a bit misleading, +because the pre-commit software should already be installed on your computer +before you can run it. + + +## Create an Empty Repository on GitHub + +At this stage, you can contact a member of QC-Devs +who has permission to create a new repository in the theochem organization. +This person will create an empty repository for you. + + +## Configure the Remote `origin`, Commit and Push + +The following commands will upload your local work online: + +```bash +git add . +git commit -a -m "Initial commit" +git remote add origin git@github.com:theochem/${your-fancy-project-name}.git +git push -u origin main +``` From 41a6cabe94a4409882afb446aa2b1d88691b0497 Mon Sep 17 00:00:00 2001 From: Toon Verstraelen Date: Wed, 19 Jun 2024 12:01:48 +0200 Subject: [PATCH 2/4] Fix typo --- MAINTAINING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MAINTAINING.md b/MAINTAINING.md index ec212ac..f4cd1db 100644 --- a/MAINTAINING.md +++ b/MAINTAINING.md @@ -21,7 +21,7 @@ As with all of our work, contributions to this document are welcome. and adding a few files that should always be present. 2. Python package - - Setup tools (TODO) + - Setuptools (TODO) - Recommended Packages to facilitate developemnt (TODO) 3. Documentation From 5a3c799c0e04b72e98a59baa71cc5a0363435778 Mon Sep 17 00:00:00 2001 From: Toon Verstraelen Date: Fri, 21 Jun 2024 09:45:10 +0200 Subject: [PATCH 3/4] Suggestions from Fanwang --- MAINTAINING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/MAINTAINING.md b/MAINTAINING.md index f4cd1db..43ff40d 100644 --- a/MAINTAINING.md +++ b/MAINTAINING.md @@ -5,7 +5,7 @@ This document discusses our default repository setup. It can be used as a set of step-by-step instructions for starting a new repository or upgrading an existing one. -The goal is to achieve more consistency across all QC-Devs projects, +The goal is to achieve more consistency across all [QC-Devs](https://qcdevs.org/) projects, and to provide tools to make your repository welcoming to contributions in a way that is consistent with our [Contributor Guide](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md). @@ -14,7 +14,7 @@ This guide is a modular collection of mini-tutorials for setting up your repository and learning best practices. As with all of our work, contributions to this document are welcome. -## Repository setup +## Repository Setup 1. The [Minimal Initial Repository](maintaining/minimal.md) walks you through the first steps of setting up a Git repository (locally and on GitHub) From a2c5255fdf4ec81e877f58e1ec07d86ed94e91e0 Mon Sep 17 00:00:00 2001 From: Toon Verstraelen Date: Fri, 21 Jun 2024 10:14:32 +0200 Subject: [PATCH 4/4] Clarify scope and improve structure --- MAINTAINING.md | 61 ++++++++++++++++++++++++++++----------- maintaining/pre-commit.md | 12 ++++++++ 2 files changed, 56 insertions(+), 17 deletions(-) create mode 100644 maintaining/pre-commit.md diff --git a/MAINTAINING.md b/MAINTAINING.md index 43ff40d..addccfb 100644 --- a/MAINTAINING.md +++ b/MAINTAINING.md @@ -16,24 +16,51 @@ As with all of our work, contributions to this document are welcome. ## Repository Setup -1. The [Minimal Initial Repository](maintaining/minimal.md) walks you through the first steps - of setting up a Git repository (locally and on GitHub) - and adding a few files that should always be present. +### A. Minimal Repository + +The [Minimal Initial Repository](maintaining/minimal.md) walks you through the first steps +of setting up a Git repository (locally and on GitHub) +and adding a few files that should always be present. +This is only the minimal setup, +meaning that more files will be added in the following mini-tutorials, +if they apply to your use case, such setting up a Python package. + + +### B. Project-specific Steps + +There are several types of repositories, and each comes with its own set of recommendations: + +1. Python packages -2. Python package - Setuptools (TODO) - Recommended Packages to facilitate developemnt (TODO) -3. Documentation - - Changelogs (TODO) - - Sphinkx (TODO) - - Jupyter Book (TODO) - -4. Continuous integration - - Pre-commit (TODO) - - Unit testing (TODO) - - Code coverage (TODO) - - Documentation build and deployment (TODO) - - Deployment on PyPI (TODO) - - Deepsource analysis (TODO) - - Sourcery AI pull request review (TODO) +2. Research Project + + - Reproducible Python environment with pip-tools (TODO) + + +### C. Continuous Integration + +A good continuous integration setup lowers the maintenance burden +and automates part of the review process. + +- [Pre-commit](maintaining/pre-commit.md) is strongly recommended for any type of project, + and therefore included in the minimal setup. + This tutorial documents the integration with [pre-commit.ci](http://pre-commit.ci/). +- Unit testing (TODO) +- Code coverage (TODO) +- Documentation build and deployment (TODO) +- Deployment on PyPI (TODO) +- Deepsource analysis (TODO) +- Sourcery AI pull request review (TODO) + + +### D. Documentation + +Documentation is always useful, for which we have several recommendations. +They can be combined, but don't have to: + +- Changelogs (TODO) +- Sphinkx (TODO) +- Jupyter Book (TODO) diff --git a/maintaining/pre-commit.md b/maintaining/pre-commit.md new file mode 100644 index 0000000..fe6689e --- /dev/null +++ b/maintaining/pre-commit.md @@ -0,0 +1,12 @@ +# Integration with [pre-commit.ci](https://pre-commit.ci/) + +The [pre-commit](https://pre-commit.com/) tools as such is already improves code quality. +It becomes even better when it is integrated in your continuous integration setup. +This feature must be enabled per repository by one of the +[Theochem organization owners](https://github.com/orgs/theochem/people?query=role%3Aowner). + +Pre-commit continuous integration is possible and recommended under the following conditions: + +- Your repository is public. +- Your repository has a `.pre-commit-config.yaml` file. +- The repository is not too large in size.