docs: update repository settings

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 <project:../management/settings.md>, 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.
 

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

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 <project:settings.md>.

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).
+```
+
+:::::
+::::::

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 <project:../management/settings.md>, 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.