Quickstart Guide¶
Requirements¶
Install pipx:
python -m pip install --user pipx
python -m pipx ensurepath
Install cruft:
pipx install cruft[pyproject]
Install Poetry:
pipx install poetry
Install Nox and nox-poetry:
pipx install nox
pipx inject nox nox-poetry
pipx is preferred, but you can also install with pip install --user.
It is recommended to set up Python 3.10, 3.11 and 3.12 using pyenv.
Creating a project¶
Generate a Python project:
cruft create https://github.com/statisticsnorway/ssb-pypitemplate.git --checkout=2024.11.27
Cruft downloads the template and asks you a series of questions about project variables. Further details can be found in the Creating a project section of the user guide.
Change to the root directory of your new project, and create a Git repository:
git init
git add .
git commit
Installing the environment¶
Install the virtual environment using the command:
poetry update
Testing¶
Run the full test suite:
nox
List the available Nox sessions:
nox --list-sessions
Install the pre-commit hooks:
nox -s pre-commit -- install
If you want to run the tests with a non-default python version:
nox --force-python 3.11
Continuous Integration¶
GitHub¶
Sign up at GitHub.
Create an empty repository for your project.
Follow the instructions to push an existing repository from the command line.
PyPI¶
Sign up at PyPI.
Go to the Account Settings on PyPI, select Publishing, and set up a new pending publisher as described on Creating a PyPI Project with a Trusted Publisher.
Use the following information for the new pending publisher:
PyPI Project name: Name of the GitHub repo.
Owner: GitHub organization name or GitHub username that owns the repository.
Repository name: Name of the GitHub repo.
Workflow name:
release.ymlEnvironment: Leave empty.
TestPyPI¶
Sign up at TestPyPI.
Go to the Account Settings on TestPyPI, select Publishing, and set up a new pending publisher as described on Creating a PyPI Project with a Trusted Publisher.
Use the following information for the new pending publisher:
PyPI Project name: Name of the GitHub repo.
Owner: GitHub organization name or GitHub username that owns the repository.
Repository name: Name of the GitHub repo.
Workflow name:
release.ymlEnvironment: Leave empty.
GitHub Pages¶
Log in to GitHub.
Select Settings, Pages and set Source to “GitHub Actions” below the Build and Deployment heading.
GitHub Pages should then work out of the box. The pages are deployed to
<github username>.github.io/<repo name> or
<github organization>.github.io/<repo name>.
SonarCloud¶
Log in to SonarCloud with your GitHub account.
Click the plus-sign at upper right and select Analyze new project, select your organization and the new repo to analyze, and then click the Set Up button.
Set new code to be based on Number of days and 60 days (suggestion). And then click the Create project button.
Select Administration, Analysis Method and choose method: With GitHub Actions.
Follow the description to add a GitHub repository secret for the
SONAR_TOKEN.That’s it. The next time a pull request is opened or a branch or merged to main on GitHub, the code will be analysed by SonarCloud.
Releasing¶
Releases are triggered by a version bump on the default branch. It is recommended to do this in a separate pull request:
Switch to a branch.
Bump the version using poetry version.
Commit and push to GitHub.
Open a pull request.
Merge the pull request.
The Release workflow performs the following automated steps:
Build and upload the package to PyPI.
Apply a version tag to the repository.
Publish a GitHub Release.
Release notes are populated with the titles and authors of merged pull requests. You can group the pull requests into separate sections by applying labels to them, like this:
Pull Request Label |
Section in Release Notes |
|---|---|
|
💥 Breaking Changes |
|
🚀 Features |
|
🔥 Removals and Deprecations |
|
🐞 Fixes |
|
🐎 Performance |
|
🚨 Testing |
|
👷 Continuous Integration |
|
📚 Documentation |
|
🔨 Refactoring |
|
💄 Style |
|
📦 Dependencies |