From 5c9e9138b1770716666fb6839d5f00f0225d1e62 Mon Sep 17 00:00:00 2001 From: Xuan Hu Date: Thu, 23 May 2024 00:01:21 +0800 Subject: [PATCH 1/3] docs: update the "Tempalte and Dependency Update" --- .renovaterc.json | 2 +- docs/management/update.md | 62 ++++++++++++++++++++++++--------- template/.renovaterc.json.jinja | 2 +- 3 files changed, 48 insertions(+), 18 deletions(-) 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/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/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$", From 7535b3416cf4ce864f4f4ee86e87e63854f7f696 Mon Sep 17 00:00:00 2001 From: Xuan Hu Date: Thu, 23 May 2024 00:03:27 +0800 Subject: [PATCH 2/3] update template --- template/docs/management/update.md | 52 ++++++++++++++++++++++++ template/docs/management/update.md.jinja | 22 ---------- 2 files changed, 52 insertions(+), 22 deletions(-) create mode 100644 template/docs/management/update.md delete mode 100644 template/docs/management/update.md.jinja 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/). From b19619d0f68664de8770206dcb13315fa8193339 Mon Sep 17 00:00:00 2001 From: Xuan Hu Date: Thu, 23 May 2024 00:07:17 +0800 Subject: [PATCH 3/3] Add semantic-release in README features --- README.md | 1 + includes/sample.jinja | 1 + 2 files changed, 2 insertions(+) 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/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].