diff --git a/docs/development/commit.md b/docs/development/commit.md index 0ae0469c..dc30dca9 100644 --- a/docs/development/commit.md +++ b/docs/development/commit.md @@ -43,7 +43,7 @@ A "breaking change" refers to any modification that disrupts the existing functi ## Commit in Development Branches While the commit convention seems strict, we aim for flexibility during the development phase. -By adhering to the [project configuration](../management/config.md), all changes should be introduced via pull/merge requests. +By adhering to the , all changes should be introduced via pull/merge requests. Using the squash merge strategy, the emphasis is primarily on the title of pull/merge requests. In this way, individual commit within development branches does not need to strictly adhere to the commit convention. diff --git a/docs/management/config.md b/docs/management/config.md deleted file mode 100644 index 7b8ad978..00000000 --- a/docs/management/config.md +++ /dev/null @@ -1,90 +0,0 @@ -# Repository Configuration - -There are several configurations to utilize the features provided by the project template. These are only the essential ones, you can adjust according to your project's actual needs. - -::::{tab-set} - -:::{tab-item} GitHub -:sync: github - -1. Branch protection: - 1. Navigate to the [Branch protection rules](https://github.com/serious-scaffold/ss-python/settings/branches) settings. - 1. Ensure a rule for the default `main` branch. - 1. Enable **Require a pull request before merging** with **Require approvals** and **Dismiss stale pull request approvals when new commits are pushed** enabled. - 1. Enable **Require status checks to pass before merging** and set [ci](https://github.com/serious-scaffold/ss-python/actions/workflows/ci.yml) and [commitlint](https://github.com/serious-scaffold/ss-python/actions/workflows/commitlint.yml) as required status checks. -1. Tag protection: - 1. Navigate to the [Protected tags](https://github.com/serious-scaffold/ss-python/settings/tag_protection) settings. - 1. Create a rule for tag name pattern `v*`. -1. Squash merge enforcement: - 1. Navigate to the [General](https://github.com/serious-scaffold/ss-python/settings) settings and the **Pull Requests** section. - 1. Disable **Allow merge commits** and **Allow rebase merging**. - 1. Enable **Allow squash merging** and set **Pull request title** as **Default commit message**. -1. GitHub Pages with GitHub Actions: - 1. Navigate to the [GitHub Pages](https://github.com/serious-scaffold/ss-python/settings/pages) settings. - 1. Set **GitHub Actions** as **Source**. -1. Package publish authentication: - 1. Navigate to the [Actions secrets and variables](https://github.com/serious-scaffold/ss-python/settings/secrets/actions) settings. - 1. Set the **variable** `PDM_PUBLISH_REPO`, the repository (package index) URL to upload the package which defaults to `https://pypi.org`, the official PyPI. - 1. Set the **variable** `PDM_PUBLISH_USERNAME`, the username to authenticate to the repository (package index) which defaults to `__token__`, used for [API token](https://pypi.org/help/#apitoken). - 1. Set the **secret** `PDM_PUBLISH_PASSWORD`, the password to authenticate to the repository (package index). -1. Renovate & semantic-release authentication: - - There are two approaches, either with GitHub App or with personal access token (classic). GitHub App is the more recommended way to avoid the issues and pull requests tied to a particular user. - - ::::{tab-set} - - :::{tab-item} GitHub App - 1. [Register a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) with permission listed [here](https://docs.renovatebot.com/modules/platform/github/#running-as-a-github-app). - 1. [Generate a private key](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps#generating-private-keys), and download the private key as a `.pem` file. - 1. Navigate to the [Actions secrets and variables](https://github.com/serious-scaffold/ss-python/settings/secrets/actions) settings. - 1. Set **App ID** of the GitHub App as **variable** `BOT_APP_ID`. - 1. Set the content of the private key as **secret** `BOT_PRIVATE_KEY`. - ::: - - :::{tab-item} personal access token (classic) - 1. [Create a personal access token (classic)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) with **workflow** scope. - 1. Navigate to the [Actions secrets and variables](https://github.com/serious-scaffold/ss-python/settings/secrets/actions) settings and set the token as a **secret** `PAT`. - ::: - - :::: - -```{note} -You can set the scope of the variables and secrets to **Repository** or **Organization** according to actual requirements. -``` - -::: - -:::{tab-item} GitLab -:sync: gitlab - -1. Branch protection: - 1. Navigate to the [Repository](https://gitlab.com/serious-scaffold/ss-python/-/settings/repository) settings and the **Protected branches** section. - 1. Ensure the default `main` branch is protected with **Maintainers** for **Allowed to merge**, **No one** for **Allowed to push and merge** and **Allowed to force push** disabled. -1. Tag protection: - 1. Navigate to the [Repository](https://gitlab.com/serious-scaffold/ss-python/-/settings/repository) settings and the **Protected tags** section. - 1. Add a rule with wildcard `v*` for **Tag** and **Maintainers** for **Allowed to create**. -1. Squash merge and pipeline check enforcement: - 1. Navigate to the [Merge requests](https://gitlab.com/serious-scaffold/ss-python/-/settings/merge_requests) settings. - 1. Set **Fast-forward merge** for the **Merge method**. - 1. Set **Require** for the **Squash commits when merging**. - 1. Enable **Pipelines must succeed** in the **Merge checks**. -1. Package publish authentication: - 1. Navigate to the [CI/CD](https://gitlab.com/serious-scaffold/ss-python/-/settings/ci_cd) settings and the **Variables** section. - 1. Set the variable `PDM_PUBLISH_REPO`, the repository (package index) URL to upload the package, default to `https://pypi.org`, the official PyPI. - 1. Set the variable `PDM_PUBLISH_USERNAME`, the username to authenticate to the repository (package index), default to `__token__`, used for [API token](https://pypi.org/help/#apitoken). - 1. Set the variable `PDM_PUBLISH_PASSWORD` with the **Mask variable** option for security, the password to authenticate to the repository (package index). -1. Renovate & semantic-release authentication: - - Either [Group access tokens](https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html), [Project access tokens](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html) or [Personal access tokens](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) can be used. The group or project access tokens are more recommended to avoid the issues and merge requests tied to particular user. - - 1. Create a [group access token](https://gitlab.com/groups/serious-scaffold/-/settings/access_tokens), [project access token](https://gitlab.com/serious-scaffold/ss-python/-/settings/access_tokens) or [personal access token](https://gitlab.com/-/user_settings/personal_access_tokens) with `Maintainer` role and `api, write_repository` scope. - 1. Navigate to the [CI/CD](https://gitlab.com/serious-scaffold/ss-python/-/settings/ci_cd) settings and the **Variables** section. Set the token as variable `PAT` with the **Mask variable** option for security. - 1. Navigate to the [Pipeline schedules](https://gitlab.com/serious-scaffold/ss-python/-/pipeline_schedules). Create a new schedule with `*/15 0-3 * * 1` as **Interval Pattern** and mark it as **Activated**. - - ```{note} - Although optional, [creating a personal access token (classic)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) on **GitHub** is strongly recommended. This token only needs `read-only` access and will increase the rate limit for Renovate to fetch dependencies and changelogs from github.com. It can be from any account and should be set as the variable `GITHUB_COM_TOKEN` with the **Mask variable** option for security. For more information on setting this up, see [Renovate's documentation](https://docs.renovatebot.com/getting-started/running/#githubcom-token-for-changelogs). - ``` - -::: - -:::: diff --git a/docs/management/index.md b/docs/management/index.md index a097879c..c78bd51f 100644 --- a/docs/management/index.md +++ b/docs/management/index.md @@ -4,7 +4,7 @@ This section is designed for project maintainers and covers essential tasks for ```{toctree} init -config +settings update release ``` diff --git a/docs/management/release.md b/docs/management/release.md index 064e6d6e..1bc2af6a 100644 --- a/docs/management/release.md +++ b/docs/management/release.md @@ -1,6 +1,6 @@ # Release Process -The release process is primarily automated to ensure consistency and efficiency. The automation is mostly handled by GitHub Actions or GitLab CI/CD, with the help of [semantic-release](https://github.com/semantic-release/semantic-release). To ensure seamless execution, maintainers should follow specific guidelines and conventions throughout the development and release cycles. +With the integration of [semantic-release](https://github.com/semantic-release/semantic-release), the whole release process is fully automated. We just need to ensure everything is properly configured and adhere to the required commit convention. The release process includes the following tasks: @@ -55,4 +55,4 @@ Releasing a new version based on an old commit can be useful in scenarios where 1. **Valid Release Tags:** Ensure that tags are not only compatible with semantic versioning but also unique and represent a version that is newer than any previously released. 1. **Commit Convention:** While not mandatory, it is beneficial to ensure an informative changelog by following the [Commit Convention](../development/commit.md#commit-message-pattern) so that corresponding commit messages can be included in the changelog. -1. **Package Repository Configuration:** Make sure the package upload destination is properly configured as mentioned in the [project configuration](./config.md). +1. **Package Repository Configuration:** Make sure the package upload destination is properly configured as mentioned in the . diff --git a/docs/management/settings.md b/docs/management/settings.md new file mode 100644 index 00000000..04156e63 --- /dev/null +++ b/docs/management/settings.md @@ -0,0 +1,167 @@ +# Repository Settings + +There are several settings to utilize the features provided by the project template. Although some of them are not strictly required, it is highly recommended finish these one-time jobs so as to benefit on the whole development lifecycle. + +## Branch protection + +::::{tab-set} + +:::{tab-item} GitHub +:sync: github + +1. Navigate to the [Branch protection rules](https://github.com/serious-scaffold/ss-python/settings/branches) settings. +1. Ensure a rule for the default `main` branch. +1. Enable **Require a pull request before merging** with **Require approvals** and **Dismiss stale pull request approvals when new commits are pushed** enabled. +1. Enable **Require status checks to pass before merging** and set [ci](https://github.com/serious-scaffold/ss-python/actions/workflows/ci.yml) and [commitlint](https://github.com/serious-scaffold/ss-python/actions/workflows/commitlint.yml) as required status checks. + +::: + +:::{tab-item} GitLab +:sync: gitlab + +1. Navigate to the [Repository](https://gitlab.com/serious-scaffold/ss-python/-/settings/repository) settings and the **Protected branches** section. +1. Ensure the default `main` branch is protected with **Maintainers** for **Allowed to merge**, **No one** for **Allowed to push and merge** and **Allowed to force push** disabled. + +::: +:::: + +## Tag protection + +::::{tab-set} + +:::{tab-item} GitHub +:sync: github + +1. Navigate to the [Protected tags](https://github.com/serious-scaffold/ss-python/settings/tag_protection) settings. +1. Create a rule for tag name pattern `v*`. + +::: + +:::{tab-item} GitLab +:sync: gitlab + +1. Navigate to the [Repository](https://gitlab.com/serious-scaffold/ss-python/-/settings/repository) settings and the **Protected tags** section. +1. Add a rule with wildcard `v*` for **Tag** and **Maintainers** for **Allowed to create**. + +::: +:::: + +## Squash merge + +::::{tab-set} + +:::{tab-item} GitHub +:sync: github + +1. Navigate to the [General](https://github.com/serious-scaffold/ss-python/settings) settings and the **Pull Requests** section. +1. Disable **Allow merge commits** and **Allow rebase merging**. +1. Enable **Allow squash merging** and set **Pull request title** as **Default commit message**. + +::: + +:::{tab-item} GitLab +:sync: gitlab + +1. Navigate to the [Merge requests](https://gitlab.com/serious-scaffold/ss-python/-/settings/merge_requests) settings. +1. Set **Fast-forward merge** for the **Merge method**. +1. Set **Require** for the **Squash commits when merging**. +1. Enable **Pipelines must succeed** in the **Merge checks**. + +::: +:::: + +## Pages + +::::{tab-set} + +:::{tab-item} GitHub +:sync: github + +1. Navigate to the [GitHub Pages](https://github.com/serious-scaffold/ss-python/settings/pages) settings. +1. Set **GitHub Actions** as **Source**. + +::: + +:::{tab-item} GitLab +:sync: gitlab + +Nothing need to do for GitLab Pages. + +::: +:::: + +## Package publish + +::::{tab-set} + +:::{tab-item} GitHub +:sync: github + +1. Navigate to the [Actions secrets and variables](https://github.com/serious-scaffold/ss-python/settings/secrets/actions) settings. +1. Set the **variable** `PDM_PUBLISH_REPO`, the repository (package index) URL to upload the package which defaults to `https://pypi.org`, the official PyPI. +1. Set the **variable** `PDM_PUBLISH_USERNAME`, the username to authenticate to the repository (package index) which defaults to `__token__`, used for [API token](https://pypi.org/help/#apitoken). +1. Set the **secret** `PDM_PUBLISH_PASSWORD`, the password to authenticate to the repository (package index). + +::: + +:::{tab-item} GitLab +:sync: gitlab + +1. Navigate to the [CI/CD](https://gitlab.com/serious-scaffold/ss-python/-/settings/ci_cd) settings and the **Variables** section. +1. Set the variable `PDM_PUBLISH_REPO`, the repository (package index) URL to upload the package, default to `https://pypi.org`, the official PyPI. +1. Set the variable `PDM_PUBLISH_USERNAME`, the username to authenticate to the repository (package index), default to `__token__`, used for [API token](https://pypi.org/help/#apitoken). +1. Set the variable `PDM_PUBLISH_PASSWORD` with the **Mask variable** option for security, the password to authenticate to the repository (package index). + +::: +:::: + +## Renovate & semantic-release + +::::::{tab-set} + +:::::{tab-item} GitHub +:sync: github + +There are two approaches, either with GitHub App or with personal access token (classic). GitHub App is the more recommended way to avoid the issues and pull requests tied to a particular user. + +::::{tab-set} + +:::{tab-item} GitHub App + + 1. [Register a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) with permission listed [here](https://docs.renovatebot.com/modules/platform/github/#running-as-a-github-app) and `Repository administration: write` permission as mentioned [here](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/configuring-tag-protection-rules#about-tag-protection-rules). + 1. [Generate a private key](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps#generating-private-keys), and download the private key as a `.pem` file. + 1. Navigate to the [Actions secrets and variables](https://github.com/serious-scaffold/ss-python/settings/secrets/actions) settings. + 1. Set **App ID** of the GitHub App as **variable** `BOT_APP_ID`. + 1. Set the content of the private key as **secret** `BOT_PRIVATE_KEY`. + +::: + +:::{tab-item} personal access token (classic) + +1. [Create a personal access token (classic)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) with **workflow** scope. +1. Navigate to the [Actions secrets and variables](https://github.com/serious-scaffold/ss-python/settings/secrets/actions) settings and set the token as a **secret** `PAT`. + +::: +:::: + +```{note} +You can set the scope of the variables and secrets to **Repository** or **Organization** according to actual requirements. +``` + +::::: + +:::::{tab-item} GitLab +:sync: gitlab + +Either [Group access tokens](https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html), [Project access tokens](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html) or [Personal access tokens](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) can be used. The group or project access tokens are more recommended to avoid the issues and merge requests tied to particular user. + +1. Create a [group access token](https://gitlab.com/groups/serious-scaffold/-/settings/access_tokens), [project access token](https://gitlab.com/serious-scaffold/ss-python/-/settings/access_tokens) or [personal access token](https://gitlab.com/-/user_settings/personal_access_tokens) with `Maintainer` role and `api, write_repository` scope. +1. Navigate to the [CI/CD](https://gitlab.com/serious-scaffold/ss-python/-/settings/ci_cd) settings and the **Variables** section. Set the token as variable `PAT` with the **Mask variable** option for security. +1. Navigate to the [Pipeline schedules](https://gitlab.com/serious-scaffold/ss-python/-/pipeline_schedules). Create a new schedule with `*/15 0-3 * * 1` as **Interval Pattern** and mark it as **Activated**. + +```{note} +Although optional, [creating a personal access token (classic)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) on **GitHub** is strongly recommended. This token only needs `read-only` access and will increase the rate limit for Renovate to fetch dependencies and changelogs from github.com. It can be from any account and should be set as the variable `GITHUB_COM_TOKEN` with the **Mask variable** option for security. For more information on setting this up, see [Renovate's documentation](https://docs.renovatebot.com/getting-started/running/#githubcom-token-for-changelogs). +``` + +::::: +:::::: diff --git a/template/docs/development/commit.md b/template/docs/development/commit.md index 0ae0469c..dc30dca9 100644 --- a/template/docs/development/commit.md +++ b/template/docs/development/commit.md @@ -43,7 +43,7 @@ A "breaking change" refers to any modification that disrupts the existing functi ## Commit in Development Branches While the commit convention seems strict, we aim for flexibility during the development phase. -By adhering to the [project configuration](../management/config.md), all changes should be introduced via pull/merge requests. +By adhering to the , all changes should be introduced via pull/merge requests. Using the squash merge strategy, the emphasis is primarily on the title of pull/merge requests. In this way, individual commit within development branches does not need to strictly adhere to the commit convention. diff --git a/template/docs/management/config.md.jinja b/template/docs/management/config.md.jinja deleted file mode 100644 index 6e4eb45c..00000000 --- a/template/docs/management/config.md.jinja +++ /dev/null @@ -1,90 +0,0 @@ -# Repository Configuration - -There are several configurations to utilize the features provided by the project template. These are only the essential ones, you can adjust according to your project's actual needs. - -::::{tab-set} - -:::{tab-item} GitHub -:sync: github - -1. Branch protection: - 1. Navigate to the [Branch protection rules](https://github.com/{{ repo_namespace }}/{{ repo_name }}/settings/branches) settings. - 1. Ensure a rule for the default `main` branch. - 1. Enable **Require a pull request before merging** with **Require approvals** and **Dismiss stale pull request approvals when new commits are pushed** enabled. - 1. Enable **Require status checks to pass before merging** and set [ci](https://github.com/{{ repo_namespace }}/{{ repo_name }}/actions/workflows/ci.yml) and [commitlint](https://github.com/{{ repo_namespace }}/{{ repo_name }}/actions/workflows/commitlint.yml) as required status checks. -1. Tag protection: - 1. Navigate to the [Protected tags](https://github.com/{{ repo_namespace }}/{{ repo_name }}/settings/tag_protection) settings. - 1. Create a rule for tag name pattern `v*`. -1. Squash merge enforcement: - 1. Navigate to the [General](https://github.com/{{ repo_namespace }}/{{ repo_name }}/settings) settings and the **Pull Requests** section. - 1. Disable **Allow merge commits** and **Allow rebase merging**. - 1. Enable **Allow squash merging** and set **Pull request title** as **Default commit message**. -1. GitHub Pages with GitHub Actions: - 1. Navigate to the [GitHub Pages](https://github.com/{{ repo_namespace }}/{{ repo_name }}/settings/pages) settings. - 1. Set **GitHub Actions** as **Source**. -1. Package publish authentication: - 1. Navigate to the [Actions secrets and variables](https://github.com/{{ repo_namespace }}/{{ repo_name }}/settings/secrets/actions) settings. - 1. Set the **variable** `PDM_PUBLISH_REPO`, the repository (package index) URL to upload the package which defaults to `https://pypi.org`, the official PyPI. - 1. Set the **variable** `PDM_PUBLISH_USERNAME`, the username to authenticate to the repository (package index) which defaults to `__token__`, used for [API token](https://pypi.org/help/#apitoken). - 1. Set the **secret** `PDM_PUBLISH_PASSWORD`, the password to authenticate to the repository (package index). -1. Renovate & semantic-release authentication: - - There are two approaches, either with GitHub App or with personal access token (classic). GitHub App is the more recommended way to avoid the issues and pull requests tied to a particular user. - - ::::{tab-set} - - :::{tab-item} GitHub App - 1. [Register a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) with permission listed [here](https://docs.renovatebot.com/modules/platform/github/#running-as-a-github-app). - 1. [Generate a private key](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps#generating-private-keys), and download the private key as a `.pem` file. - 1. Navigate to the [Actions secrets and variables](https://github.com/{{ repo_namespace }}/{{ repo_name }}/settings/secrets/actions) settings. - 1. Set **App ID** of the GitHub App as **variable** `BOT_APP_ID`. - 1. Set the content of the private key as **secret** `BOT_PRIVATE_KEY`. - ::: - - :::{tab-item} personal access token (classic) - 1. [Create a personal access token (classic)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) with **workflow** scope. - 1. Navigate to the [Actions secrets and variables](https://github.com/{{ repo_namespace }}/{{ repo_name }}/settings/secrets/actions) settings and set the token as a **secret** `PAT`. - ::: - - :::: - -```{note} -You can set the scope of the variables and secrets to **Repository** or **Organization** according to actual requirements. -``` - -::: - -:::{tab-item} GitLab -:sync: gitlab - -1. Branch protection: - 1. Navigate to the [Repository](https://gitlab.com/{{ repo_namespace }}/{{ repo_name }}/-/settings/repository) settings and the **Protected branches** section. - 1. Ensure the default `main` branch is protected with **Maintainers** for **Allowed to merge**, **No one** for **Allowed to push and merge** and **Allowed to force push** disabled. -1. Tag protection: - 1. Navigate to the [Repository](https://gitlab.com/{{ repo_namespace }}/{{ repo_name }}/-/settings/repository) settings and the **Protected tags** section. - 1. Add a rule with wildcard `v*` for **Tag** and **Maintainers** for **Allowed to create**. -1. Squash merge and pipeline check enforcement: - 1. Navigate to the [Merge requests](https://gitlab.com/{{ repo_namespace }}/{{ repo_name }}/-/settings/merge_requests) settings. - 1. Set **Fast-forward merge** for the **Merge method**. - 1. Set **Require** for the **Squash commits when merging**. - 1. Enable **Pipelines must succeed** in the **Merge checks**. -1. Package publish authentication: - 1. Navigate to the [CI/CD](https://gitlab.com/{{ repo_namespace }}/{{ repo_name }}/-/settings/ci_cd) settings and the **Variables** section. - 1. Set the variable `PDM_PUBLISH_REPO`, the repository (package index) URL to upload the package, default to `https://pypi.org`, the official PyPI. - 1. Set the variable `PDM_PUBLISH_USERNAME`, the username to authenticate to the repository (package index), default to `__token__`, used for [API token](https://pypi.org/help/#apitoken). - 1. Set the variable `PDM_PUBLISH_PASSWORD` with the **Mask variable** option for security, the password to authenticate to the repository (package index). -1. Renovate & semantic-release authentication: - - Either [Group access tokens](https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html), [Project access tokens](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html) or [Personal access tokens](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) can be used. The group or project access tokens are more recommended to avoid the issues and merge requests tied to particular user. - - 1. Create a [group access token](https://gitlab.com/groups/{{ repo_namespace }}/-/settings/access_tokens), [project access token](https://gitlab.com/{{ repo_namespace }}/{{ repo_name }}/-/settings/access_tokens) or [personal access token](https://gitlab.com/-/user_settings/personal_access_tokens) with `Maintainer` role and `api, write_repository` scope. - 1. Navigate to the [CI/CD](https://gitlab.com/{{ repo_namespace }}/{{ repo_name }}/-/settings/ci_cd) settings and the **Variables** section. Set the token as variable `PAT` with the **Mask variable** option for security. - 1. Navigate to the [Pipeline schedules](https://gitlab.com/{{ repo_namespace }}/{{ repo_name }}/-/pipeline_schedules). Create a new schedule with `*/15 0-3 * * 1` as **Interval Pattern** and mark it as **Activated**. - - ```{note} - Although optional, [creating a personal access token (classic)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) on **GitHub** is strongly recommended. This token only needs `read-only` access and will increase the rate limit for Renovate to fetch dependencies and changelogs from github.com. It can be from any account and should be set as the variable `GITHUB_COM_TOKEN` with the **Mask variable** option for security. For more information on setting this up, see [Renovate's documentation](https://docs.renovatebot.com/getting-started/running/#githubcom-token-for-changelogs). - ``` - -::: - -:::: diff --git a/template/docs/management/index.md b/template/docs/management/index.md index a097879c..c78bd51f 100644 --- a/template/docs/management/index.md +++ b/template/docs/management/index.md @@ -4,7 +4,7 @@ This section is designed for project maintainers and covers essential tasks for ```{toctree} init -config +settings update release ``` diff --git a/template/docs/management/release.md.jinja b/template/docs/management/release.md.jinja index 4a76df62..ee778b28 100644 --- a/template/docs/management/release.md.jinja +++ b/template/docs/management/release.md.jinja @@ -1,6 +1,6 @@ # Release Process -The release process is primarily automated to ensure consistency and efficiency. The automation is mostly handled by GitHub Actions or GitLab CI/CD, with the help of [semantic-release](https://github.com/semantic-release/semantic-release). To ensure seamless execution, maintainers should follow specific guidelines and conventions throughout the development and release cycles. +With the integration of [semantic-release](https://github.com/semantic-release/semantic-release), the whole release process is fully automated. We just need to ensure everything is properly configured and adhere to the required commit convention. The release process includes the following tasks: @@ -55,4 +55,4 @@ Releasing a new version based on an old commit can be useful in scenarios where 1. **Valid Release Tags:** Ensure that tags are not only compatible with semantic versioning but also unique and represent a version that is newer than any previously released. 1. **Commit Convention:** While not mandatory, it is beneficial to ensure an informative changelog by following the [Commit Convention](../development/commit.md#commit-message-pattern) so that corresponding commit messages can be included in the changelog. -1. **Package Repository Configuration:** Make sure the package upload destination is properly configured as mentioned in the [project configuration](./config.md). +1. **Package Repository Configuration:** Make sure the package upload destination is properly configured as mentioned in the . diff --git a/template/docs/management/settings.md.jinja b/template/docs/management/settings.md.jinja new file mode 100644 index 00000000..39f985d0 --- /dev/null +++ b/template/docs/management/settings.md.jinja @@ -0,0 +1,167 @@ +# Repository Settings + +There are several settings to utilize the features provided by the project template. Although some of them are not strictly required, it is highly recommended finish these one-time jobs so as to benefit on the whole development lifecycle. + +## Branch protection + +::::{tab-set} + +:::{tab-item} GitHub +:sync: github + +1. Navigate to the [Branch protection rules](https://github.com/{{ repo_namespace }}/{{ repo_name }}/settings/branches) settings. +1. Ensure a rule for the default `main` branch. +1. Enable **Require a pull request before merging** with **Require approvals** and **Dismiss stale pull request approvals when new commits are pushed** enabled. +1. Enable **Require status checks to pass before merging** and set [ci](https://github.com/{{ repo_namespace }}/{{ repo_name }}/actions/workflows/ci.yml) and [commitlint](https://github.com/{{ repo_namespace }}/{{ repo_name }}/actions/workflows/commitlint.yml) as required status checks. + +::: + +:::{tab-item} GitLab +:sync: gitlab + +1. Navigate to the [Repository](https://gitlab.com/{{ repo_namespace }}/{{ repo_name }}/-/settings/repository) settings and the **Protected branches** section. +1. Ensure the default `main` branch is protected with **Maintainers** for **Allowed to merge**, **No one** for **Allowed to push and merge** and **Allowed to force push** disabled. + +::: +:::: + +## Tag protection + +::::{tab-set} + +:::{tab-item} GitHub +:sync: github + +1. Navigate to the [Protected tags](https://github.com/{{ repo_namespace }}/{{ repo_name }}/settings/tag_protection) settings. +1. Create a rule for tag name pattern `v*`. + +::: + +:::{tab-item} GitLab +:sync: gitlab + +1. Navigate to the [Repository](https://gitlab.com/{{ repo_namespace }}/{{ repo_name }}/-/settings/repository) settings and the **Protected tags** section. +1. Add a rule with wildcard `v*` for **Tag** and **Maintainers** for **Allowed to create**. + +::: +:::: + +## Squash merge + +::::{tab-set} + +:::{tab-item} GitHub +:sync: github + +1. Navigate to the [General](https://github.com/{{ repo_namespace }}/{{ repo_name }}/settings) settings and the **Pull Requests** section. +1. Disable **Allow merge commits** and **Allow rebase merging**. +1. Enable **Allow squash merging** and set **Pull request title** as **Default commit message**. + +::: + +:::{tab-item} GitLab +:sync: gitlab + +1. Navigate to the [Merge requests](https://gitlab.com/{{ repo_namespace }}/{{ repo_name }}/-/settings/merge_requests) settings. +1. Set **Fast-forward merge** for the **Merge method**. +1. Set **Require** for the **Squash commits when merging**. +1. Enable **Pipelines must succeed** in the **Merge checks**. + +::: +:::: + +## Pages + +::::{tab-set} + +:::{tab-item} GitHub +:sync: github + +1. Navigate to the [GitHub Pages](https://github.com/{{ repo_namespace }}/{{ repo_name }}/settings/pages) settings. +1. Set **GitHub Actions** as **Source**. + +::: + +:::{tab-item} GitLab +:sync: gitlab + +Nothing need to do for GitLab Pages. + +::: +:::: + +## Package publish + +::::{tab-set} + +:::{tab-item} GitHub +:sync: github + +1. Navigate to the [Actions secrets and variables](https://github.com/{{ repo_namespace }}/{{ repo_name }}/settings/secrets/actions) settings. +1. Set the **variable** `PDM_PUBLISH_REPO`, the repository (package index) URL to upload the package which defaults to `https://pypi.org`, the official PyPI. +1. Set the **variable** `PDM_PUBLISH_USERNAME`, the username to authenticate to the repository (package index) which defaults to `__token__`, used for [API token](https://pypi.org/help/#apitoken). +1. Set the **secret** `PDM_PUBLISH_PASSWORD`, the password to authenticate to the repository (package index). + +::: + +:::{tab-item} GitLab +:sync: gitlab + +1. Navigate to the [CI/CD](https://gitlab.com/{{ repo_namespace }}/{{ repo_name }}/-/settings/ci_cd) settings and the **Variables** section. +1. Set the variable `PDM_PUBLISH_REPO`, the repository (package index) URL to upload the package, default to `https://pypi.org`, the official PyPI. +1. Set the variable `PDM_PUBLISH_USERNAME`, the username to authenticate to the repository (package index), default to `__token__`, used for [API token](https://pypi.org/help/#apitoken). +1. Set the variable `PDM_PUBLISH_PASSWORD` with the **Mask variable** option for security, the password to authenticate to the repository (package index). + +::: +:::: + +## Renovate & semantic-release + +::::::{tab-set} + +:::::{tab-item} GitHub +:sync: github + +There are two approaches, either with GitHub App or with personal access token (classic). GitHub App is the more recommended way to avoid the issues and pull requests tied to a particular user. + +::::{tab-set} + +:::{tab-item} GitHub App + + 1. [Register a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) with permission listed [here](https://docs.renovatebot.com/modules/platform/github/#running-as-a-github-app) and `Repository administration: write` permission as mentioned [here](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/configuring-tag-protection-rules#about-tag-protection-rules). + 1. [Generate a private key](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps#generating-private-keys), and download the private key as a `.pem` file. + 1. Navigate to the [Actions secrets and variables](https://github.com/{{ repo_namespace }}/{{ repo_name }}/settings/secrets/actions) settings. + 1. Set **App ID** of the GitHub App as **variable** `BOT_APP_ID`. + 1. Set the content of the private key as **secret** `BOT_PRIVATE_KEY`. + +::: + +:::{tab-item} personal access token (classic) + +1. [Create a personal access token (classic)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) with **workflow** scope. +1. Navigate to the [Actions secrets and variables](https://github.com/{{ repo_namespace }}/{{ repo_name }}/settings/secrets/actions) settings and set the token as a **secret** `PAT`. + +::: +:::: + +```{note} +You can set the scope of the variables and secrets to **Repository** or **Organization** according to actual requirements. +``` + +::::: + +:::::{tab-item} GitLab +:sync: gitlab + +Either [Group access tokens](https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html), [Project access tokens](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html) or [Personal access tokens](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) can be used. The group or project access tokens are more recommended to avoid the issues and merge requests tied to particular user. + +1. Create a [group access token](https://gitlab.com/groups/{{ repo_namespace }}/-/settings/access_tokens), [project access token](https://gitlab.com/{{ repo_namespace }}/{{ repo_name }}/-/settings/access_tokens) or [personal access token](https://gitlab.com/-/user_settings/personal_access_tokens) with `Maintainer` role and `api, write_repository` scope. +1. Navigate to the [CI/CD](https://gitlab.com/{{ repo_namespace }}/{{ repo_name }}/-/settings/ci_cd) settings and the **Variables** section. Set the token as variable `PAT` with the **Mask variable** option for security. +1. Navigate to the [Pipeline schedules](https://gitlab.com/{{ repo_namespace }}/{{ repo_name }}/-/pipeline_schedules). Create a new schedule with `*/15 0-3 * * 1` as **Interval Pattern** and mark it as **Activated**. + +```{note} +Although optional, [creating a personal access token (classic)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) on **GitHub** is strongly recommended. This token only needs `read-only` access and will increase the rate limit for Renovate to fetch dependencies and changelogs from github.com. It can be from any account and should be set as the variable `GITHUB_COM_TOKEN` with the **Mask variable** option for security. For more information on setting this up, see [Renovate's documentation](https://docs.renovatebot.com/getting-started/running/#githubcom-token-for-changelogs). +``` + +::::: +::::::