Maintainer Guide framework

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.

MAINTAINING.md

@@ -0,0 +1,66 @@
+# 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](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).
+
+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
+
+### 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
+
+    - Setuptools (TODO)
+    - Recommended Packages to facilitate developemnt (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)

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.

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:
 

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.

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
+```

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.