diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e3c18e2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,34 @@ +# Contributing + +Thank you for your interest in contributing to this project! + +This repository serves a dual purpose: +1. It is a [Copier](https://copier.readthedocs.io/) template. +2. It is a standard GitHub template repository. + +This is achieved through a CI/CD process where the `template` branch, containing the Copier Jinja2 templates, is rendered and pushed to the `main` branch. The `main` branch can then be used as a regular GitHub template. + +## Development Workflow + +Because of this setup, all development must happen on the `template` branch. The `main` branch is protected and automatically updated. + +To contribute, please follow these steps: + +1. **Fork the repository.** +2. **Create a new branch from the `template` branch.** + ```bash + git checkout template + git checkout -b my-new-feature + ``` +3. **Make your changes.** + - Modify the template files. They have a `.jinja` extension if the content of the file is + manipulated, and the curly braces in the names is jinja too that is interpolated. + - If you're adding new template variables, update `copier.yml`. +4. **Test your changes (if applicable).** + You can test the template rendering locally using `copier`. +5. **Commit your changes and push your branch.** +6. **Open a Pull Request against the `template` branch.** + +Your pull request will be reviewed, and once merged, a GitHub Actions workflow will automatically render the updated template and commit the result to the `main` branch. + +Direct pushes or pull requests to the `main` cannot be accepted. diff --git a/README.md b/README.md index f622a87..bea1dfb 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,9 @@ It includes the following bits: - The rest of this README! ## 🤔 How to use this template +This template can be used in two ways: + +### As a GitHub Template 1. Hit the green `Use this template` button up on the right next to the stars 2. Give your new repository a name and then clone it to your dev environment. 3. Rename it: @@ -28,6 +31,14 @@ It includes the following bits: 4. Run `uv sync` 5. Have a look at the stuff below here, try out some commands and edit this README as you like! +### As a Copier Template +Alternatively, you can use [Copier](https://copier.readthedocs.io/) to generate a new project from this template. +This is the recommended approach as it allows you to configure the project with your details. + +```bash +uxv copier copy -r template https://github.com/carderne/postmodern-python +``` + ## 💾 Installation (not development!) ```bash git clone git@github.com:carderne/postmodern-python.git diff --git a/copier.yml b/copier.yml index d6c12fe..1253104 100644 --- a/copier.yml +++ b/copier.yml @@ -54,7 +54,7 @@ include_dockerfile: help: "Include a Dockerfile in the project?" default: yes -_src_path: project_template -_exlude: +_exclude: - .venv/ - .git/ + - .github/workflows/render-template.yml