Project Management

Prerequisites

copier serves as a key tool in serious-scaffold, differentiating it from other project templates. The installation can be done with the following command.

Note

Using pipx for management is recommended and you can find pipx’s installation instructions here.

# Copier: Template rendering for projects.
pipx install copier==9.2.0

Project Initialization

  1. Create a Git repository on the hosting platform. Clone it to local and navigate to the root directory.

    Note

    The provided repository URL, git@git.example.com/demo_namespace/demo_name.git, is purely for demonstration purposes.

    git clone git@git.example.com/demo_namespace/demo_name.git
cd demo_name

  2. Generate the project.

    Note

    Several questions will be prompted during this process. Your patience is appreciated for this one-time job.

    copier copy gh:serious-scaffold/ss-python .

  3. Set up the development environment.

    make dev

  4. Commit and push the initialized project.

    git add .
git commit -m "chore: Initialize from ss-python."
SKIP=no-commit-to-branch git push

  5. Bootstrap the dev container.

    Navigate to the Dev Container Workflow page and run workflow from the default branch. The container will be named following pattern ghcr.io/serious-scaffold/ss-python/dev:py<PYTHON_VERSION>, for example, ghcr.io/serious-scaffold/ss-python/dev:py3.12.

    Bootstrap Dev Container on GitHub.

    Navigate to the Run pipeline page and run pipeline for the default branch. The container will be named following pattern registry.gitlab.com/serious-scaffold/ss-python/dev:py<PYTHON_VERSION>, for example, registry.gitlab.com/serious-scaffold/ss-python/dev:py3.12.

    Bootstrap Dev Container on GitLab.

Now, everything is done for initialization.

Project 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.

  1. Branch protection:

    1. Navigate to the Branch protection rules settings.

    2. Ensure a rule for the default main branch.

    3. Enable Require a pull request before merging with Require approvals and Dismiss stale pull request approvals when new commits are pushed enabled.

    4. Enable Require status checks to pass before merging and set ci and commitlint as required status checks.

  2. Tag protection:

    1. Navigate to the Protected tags settings.

    2. Create a rule for tag name pattern v*.

  3. Squash merge enforcement:

    1. Navigate to the General settings and the Pull Requests section.

    2. Disable Allow merge commits and Allow rebase merging.

    3. Enable Allow squash merging and set Pull request title as Default commit message.

  4. GitHub Pages with GitHub Actions:

    1. Navigate to the GitHub Pages settings.

    2. Set GitHub Actions as Source.

  5. Package publish authentication:

    1. Navigate to the Actions secrets and variables settings.

    2. Set the variable PDM_PUBLISH_REPO, the repository (package index) URL to upload the package which defaults to https://pypi.org, the official PyPI.

    3. Set the variable PDM_PUBLISH_USERNAME, the username to authenticate to the repository (package index) which defaults to __token__, used for API token.

    4. Set the secret PDM_PUBLISH_PASSWORD, the password to authenticate to the repository (package index).

  6. Renovate 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.

    1. Register a GitHub App with permission listed here.

    2. Generate a private key, and download the private key as a .pem file.

    3. Navigate to the Actions secrets and variables settings.

    4. Set App ID of the GitHub App as variable BOT_APP_ID.

    5. Set the content of the private key as secret BOT_PRIVATE_KEY.

    1. Create a personal access token (classic) with workflow scope.

    2. Navigate to the Actions secrets and variables settings and set the token as a secret RENOVATE_TOKEN.

Note

You can set the scope of the variables and secrets to Repository or Organization according to actual requirements.

  1. Branch protection:

    1. Navigate to the Repository settings and the Protected branches section.

    2. 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.

  2. Tag protection:

    1. Navigate to the Repository settings and the Protected tags section.

    2. Add a rule with wildcard v* for Tag and Maintainers for Allowed to create.

  3. Squash merge and pipeline check enforcement:

    1. Navigate to the Merge requests settings.

    2. Set Fast-forward merge for the Merge method.

    3. Set Require for the Squash commits when merging.

    4. Enable Pipelines must succeed in the Merge checks.

  4. Package publish authentication:

    1. Navigate to the CI/CD settings and the Variables section.

    2. Set the variable PDM_PUBLISH_REPO, the repository (package index) URL to upload the package, default to https://pypi.org, the official PyPI.

    3. Set the variable PDM_PUBLISH_USERNAME, the username to authenticate to the repository (package index), default to __token__, used for API token.

    4. Set the variable PDM_PUBLISH_PASSWORD with the Mask variable option for security, the password to authenticate to the repository (package index).

  5. Renovate authentication:

    Either Group access tokens, Project access tokens or Personal access tokens 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, project access token or personal access token with api, write_repository scope.

    2. Navigate to the CI/CD settings and the Variables section. Set the token as variable RENOVATE_TOKEN with the Mask variable option for security.

    3. Navigate to the 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) 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.

Project 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:

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.

  2. For template-related changes, consider proposing an issue or change request directly to the template repository.

  3. 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.