diff --git a/.renovaterc.json b/.renovaterc.json index 7ec94ab7..17486a9f 100644 --- a/.renovaterc.json +++ b/.renovaterc.json @@ -73,7 +73,7 @@ { "customType": "regex", "datasourceTemplate": "npm", - "description": "Match npm packages used by npx", + "description": "Match npm packages used with npx", "fileMatch": [ "^\\.github/workflows/.+\\.yml$", "^\\.gitlab/workflows/.+\\.yml$", diff --git a/README.md b/README.md index 6af599cb..26af18b8 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,7 @@ If you find this helpful, please consider [sponsorship](https://github.com/spons - Manage configurations with [pydantic-settings](https://docs.pydantic.dev/latest/usage/pydantic_settings/). - [Dev container](https://containers.dev/) for development and GitLab CI/CD. - Automate dependency updates with [Renovate](https://github.com/renovatebot/renovate). +- Automate version management and release with [semantic-release](https://github.com/semantic-release/semantic-release). - [Versioned documentation](https://docs.readthedocs.io/en/stable/versions.html) and [pull request previews](https://docs.readthedocs.io/en/stable/pull-requests.html) with [Read the Docs](https://readthedocs.org/). - Adapted configuration for GitHub, GitLab and self-managed GitLab. - Continuous Integration for Linux, MacOS and Windows [GitHub Only]. diff --git a/docs/management/update.md b/docs/management/update.md index 535ebf2f..9404aba0 100644 --- a/docs/management/update.md +++ b/docs/management/update.md @@ -1,22 +1,52 @@ -# Template Update +# Template and Dependency Update -Thanks to the update mechanism provided natively by `copier`, when a new version of the template is released, you can easily update the project. Just run the following command under the root directory: +## Template update -```bash -copier update -``` +To update the project template, thanks to the [update feature](https://copier.readthedocs.io/en/stable/updating/) provided by [Copier](https://github.com/copier-org/copier) and the [regex manager](https://docs.renovatebot.com/modules/manager/regex/) provided by Renovate, a pull request will be automatically created when a new version of the template is released. In most cases, Copier will update the project seamlessly. If conflicts arise, they can be resolved manually since everything is version-controlled by Git. -```{note} -The `-A/--skip-answered` flag can be used to skip questions that have already been answered. -``` +### Tips to minimize potential conflicts -In most cases, `copier` will manage updates seamlessly. If conflicts arise, they can be resolved manually since everything is version-controlled by Git. +To minimize potential conflicts, consider the following suggestions: -```{tip} -To minimize potential conflicts, there are several suggestions to follow: -1. Avoid modifying the auto-generated files unless absolutely necessary. -1. For template-related changes, consider proposing an issue or change request directly to the template repository. -1. For project-specific changes, adopt an inheritance or extension approach to minimize the changes to auto-generated contents. -``` +1. Avoid modifying the auto-generated files unless necessary. +1. For template-related changes, consider proposing an issue or a pull request to the [project template repository](http://github.com/serious-scaffold/ss-python) directly. +1. For project-specific changes, adopt an inheritance or extension approach to minimize modifications to auto-generated content. + +## Dependency update + +With the integration of [Renovate](https://github.com/renovatebot/renovate), all dependencies, including those used for development and CI/CD, will be automatically updated via pull requests whenever a new version is released. This allows us to focus solely on testing to ensure the new versions do not break anything. Moreover, an issue titled "Dependency Dashboard" will be created, so that you can have an overview of the state of all dependencies. + +### Managed dependency types + +The project template tracks the following dependencies: -For more details, please refer to `copier update --help` and [the official documentation](https://copier.readthedocs.io/en/stable/updating/). +1. Supported managers other than `regex`: + 1. [pep621](https://docs.renovatebot.com/modules/manager/pep621/): The lock file generated by PDM for both dependencies and development dependencies in `pyproject.toml`. + 1. [github-actions](https://docs.renovatebot.com/modules/manager/github-actions/): Actions, runners and containers in GitHub Actions. + 1. [gitlabci](https://docs.renovatebot.com/modules/manager/gitlabci/): Containers in GitLab CI/CD. + 1. [pre-commit](https://docs.renovatebot.com/modules/manager/pre-commit/): Pre-commit hooks. +1. Regex manager: + 1. Python packages installed with pip, pipx and asdf, listed in the README, DevContainer Dockerfile, GitHub Actions, GitLab CI/CD, ReadTheDocs configuration, Renovate configuration and documentation. + 1. Debian packages installed in the DevContainer Dockerfile. + 1. PDM version specified in the `pdm-project/setup-pdm` GitHub action. + 1. NPM packages used with npx. + 1. The project template itself. + +### Add new dependencies + +When adding new dependencies that belong to the managed dependency type mentioned above, it is recommended to pin or lock their versions to ensure they are smoothly managed by Renovate. + +When adding new types of dependencies, it is also recommended to manage them with Renovate. + +- If this follows a common pattern, consider creating an issue or even sending a pull request to project template directly. +- If it is project-specific, you can extend the renovate configuration: + - For supported managers other than `regex`, add them in the Renovate configuration using environment variable `RENOVATE_ENABLED_MANAGERS` in GitHub Actions or GitLab CI/CD and configure them in the `renovaterc.json` under the root directory if needed. + - For `regex` managers, add new entries in the `customManagers` and configure `packageRules` if needed in the `.renovaterc.json`. + + ```{note} + This also adheres to the . + ``` + +```{note} +For the complete list of supported managers and their corresponding configurations, please refer to the [Managers - Renovate Docs](https://docs.renovatebot.com/modules/manager/). +``` diff --git a/includes/sample.jinja b/includes/sample.jinja index 3042df8d..37b275a9 100644 --- a/includes/sample.jinja +++ b/includes/sample.jinja @@ -22,6 +22,7 @@ If you find this helpful, please consider [sponsorship](https://github.com/spons - Manage configurations with [pydantic-settings](https://docs.pydantic.dev/latest/usage/pydantic_settings/). - [Dev container](https://containers.dev/) for development and GitLab CI/CD. - Automate dependency updates with [Renovate](https://github.com/renovatebot/renovate). +- Automate version management and release with [semantic-release](https://github.com/semantic-release/semantic-release). - [Versioned documentation](https://docs.readthedocs.io/en/stable/versions.html) and [pull request previews](https://docs.readthedocs.io/en/stable/pull-requests.html) with [Read the Docs](https://readthedocs.org/). - Adapted configuration for GitHub, GitLab and self-managed GitLab. - Continuous Integration for Linux, MacOS and Windows [GitHub Only]. diff --git a/template/.renovaterc.json.jinja b/template/.renovaterc.json.jinja index b6ab41ea..506e8040 100644 --- a/template/.renovaterc.json.jinja +++ b/template/.renovaterc.json.jinja @@ -80,7 +80,7 @@ { "customType": "regex", "datasourceTemplate": "npm", - "description": "Match npm packages used by npx", + "description": "Match npm packages used with npx", "fileMatch": [ "^\\.github/workflows/.+\\.yml$", "^\\.gitlab/workflows/.+\\.yml$", diff --git a/template/docs/management/update.md b/template/docs/management/update.md new file mode 100644 index 00000000..9404aba0 --- /dev/null +++ b/template/docs/management/update.md @@ -0,0 +1,52 @@ +# Template and Dependency Update + +## Template update + +To update the project template, thanks to the [update feature](https://copier.readthedocs.io/en/stable/updating/) provided by [Copier](https://github.com/copier-org/copier) and the [regex manager](https://docs.renovatebot.com/modules/manager/regex/) provided by Renovate, a pull request will be automatically created when a new version of the template is released. In most cases, Copier will update the project seamlessly. If conflicts arise, they can be resolved manually since everything is version-controlled by Git. + +### Tips to minimize potential conflicts + +To minimize potential conflicts, consider the following suggestions: + +1. Avoid modifying the auto-generated files unless necessary. +1. For template-related changes, consider proposing an issue or a pull request to the [project template repository](http://github.com/serious-scaffold/ss-python) directly. +1. For project-specific changes, adopt an inheritance or extension approach to minimize modifications to auto-generated content. + +## Dependency update + +With the integration of [Renovate](https://github.com/renovatebot/renovate), all dependencies, including those used for development and CI/CD, will be automatically updated via pull requests whenever a new version is released. This allows us to focus solely on testing to ensure the new versions do not break anything. Moreover, an issue titled "Dependency Dashboard" will be created, so that you can have an overview of the state of all dependencies. + +### Managed dependency types + +The project template tracks the following dependencies: + +1. Supported managers other than `regex`: + 1. [pep621](https://docs.renovatebot.com/modules/manager/pep621/): The lock file generated by PDM for both dependencies and development dependencies in `pyproject.toml`. + 1. [github-actions](https://docs.renovatebot.com/modules/manager/github-actions/): Actions, runners and containers in GitHub Actions. + 1. [gitlabci](https://docs.renovatebot.com/modules/manager/gitlabci/): Containers in GitLab CI/CD. + 1. [pre-commit](https://docs.renovatebot.com/modules/manager/pre-commit/): Pre-commit hooks. +1. Regex manager: + 1. Python packages installed with pip, pipx and asdf, listed in the README, DevContainer Dockerfile, GitHub Actions, GitLab CI/CD, ReadTheDocs configuration, Renovate configuration and documentation. + 1. Debian packages installed in the DevContainer Dockerfile. + 1. PDM version specified in the `pdm-project/setup-pdm` GitHub action. + 1. NPM packages used with npx. + 1. The project template itself. + +### Add new dependencies + +When adding new dependencies that belong to the managed dependency type mentioned above, it is recommended to pin or lock their versions to ensure they are smoothly managed by Renovate. + +When adding new types of dependencies, it is also recommended to manage them with Renovate. + +- If this follows a common pattern, consider creating an issue or even sending a pull request to project template directly. +- If it is project-specific, you can extend the renovate configuration: + - For supported managers other than `regex`, add them in the Renovate configuration using environment variable `RENOVATE_ENABLED_MANAGERS` in GitHub Actions or GitLab CI/CD and configure them in the `renovaterc.json` under the root directory if needed. + - For `regex` managers, add new entries in the `customManagers` and configure `packageRules` if needed in the `.renovaterc.json`. + + ```{note} + This also adheres to the . + ``` + +```{note} +For the complete list of supported managers and their corresponding configurations, please refer to the [Managers - Renovate Docs](https://docs.renovatebot.com/modules/manager/). +``` diff --git a/template/docs/management/update.md.jinja b/template/docs/management/update.md.jinja deleted file mode 100644 index 535ebf2f..00000000 --- a/template/docs/management/update.md.jinja +++ /dev/null @@ -1,22 +0,0 @@ -# Template Update - -Thanks to the update mechanism provided natively by `copier`, when a new version of the template is released, you can easily update the project. Just run the following command under the root directory: - -```bash -copier update -``` - -```{note} -The `-A/--skip-answered` flag can be used to skip questions that have already been answered. -``` - -In most cases, `copier` will manage updates seamlessly. If conflicts arise, they can be resolved manually since everything is version-controlled by Git. - -```{tip} -To minimize potential conflicts, there are several suggestions to follow: -1. Avoid modifying the auto-generated files unless absolutely necessary. -1. For template-related changes, consider proposing an issue or change request directly to the template repository. -1. For project-specific changes, adopt an inheritance or extension approach to minimize the changes to auto-generated contents. -``` - -For more details, please refer to `copier update --help` and [the official documentation](https://copier.readthedocs.io/en/stable/updating/).