1.1. New Repository

To create a new GitHub repository with PyPackIT pre-installed:

1. Create a repository from PyPackIT’s template repository.

2. Add a Personal Access Token (PAT) and activate external services.

3. Customize project configurations and metadata.

4. Initialize project with a commit.

Don’t Miss Step 2

Since step 2 is common for both new and existing repositories, it is explained in a separate section, while steps 1, 3, and 4 are detailed below. Don’t forget to follow all four steps in the given order.

1.1.1. Repository Creation

The first step is to create a new repository using PyPackIT’s GitHub template repository:

1. Sign in to your GitHub account.

2. Click here, or alternatively navigate to the PyPackIT template repository, click on the Use this template button on the top-right corner, and select Create a new repository from the dropdown menu.

3. Enter a name for your repository in the Repository name field.

Repository Naming

A GitHub repository name can only contain alphanumeric characters, hyphens, underscores, and periods. That is, the matching regular expression is: ^[a-zA-Z0-9._-]+$. However, the repository name can also used to derive the project name and the package name, the latter of which has additional restrictions. While you can set these separately in the control center, for consistency, it is recommended to choose a repository name that can be used to automatically derive the package name. Considering the restrictions on the repository name, this simply means that the repository name should not start with a digit, and should end with an alphanumeric character.

For example, choosing My-Project as the repository name and leaving the project and package names undefined, the project name will be automatically set to My Project, the distribution package name to My-Project (same as the repository name), and the import package name to my_project. That is, the package will be shown on PyPI as My-Project, while users can install it with pip install my-project (or any other equivalent name, due to PyPA’s name normalization), and import it with import my_project.

4. Optionally, if you are a member of an organization, you can choose to create the repository under one of your organizations (instead of your personal account) by selecting it from the Owner dropdown menu.

5. Click on the Create repository button.

Dynamic Documentation Links

Log in to our website to make links in this documentation point to your actual repository.

You will be redirected to the newly created repository in your selected account. Navigating to the repository’s Actions tab, you will see that a workflow is running. It will automatically initialize your new repository by generating all necessary files and removing extra files that belong to the PyPackIT repository but are not part of the template. While waiting for the workflow to complete and before making any other changes, follow step 2 to add a Personal Access Token (PAT) and activate external services.

1.1.2. Project Configuration

Going back to your new GitHub repository after finishing the common steps, verify that the first workflow run has completed successfully (with a green checkmark). You will see that the default initial commit has been replaced by a new commit, which contains all the generated files for your repository.

Failing Workflows

Rarely, workflows may fail due to internal GitHub errors. When a workflow fails, you will see a red cross mark next to the workflow name. In this case, you can re-run the workflow by clicking on the Re-run all jobs button. PyPackIT always generates comprehensive job reports and logs for each workflow run, which can also be investigated in case of a failure or unexpected behavior.

Your repository is now in the initialization phase. During this phase, every time you push a commit, PyPackIT will run a workflow to:

• Update all dynamic files and directories according to the new control center configurations.

• Update repository configurations, including general settings and metadata, branch names, labels, issues forms, discussions, and security settings.

• Format, refactor, lint, build, and test the package, test suite, and documentation website.

• Publish a developmental version of the package to your Anaconda channel.

• Deploy the updated website to GitHub Pages.

• Build a docker image of the repository and deploy it to GitHub Container Registry (ghcr.io) or another registry of your choice.

• Trigger a build on mybinder.org using the docker image.

• Update a draft release on GitHub.

• Update draft releases on Zenodo and/or Zenodo Sandbox.

All jobs can be fully customized (or disabled) from your repository’s control center. To start customizing your new project:

1. Navigate to the .control/proj.yaml file in the repository.

2. Replace the placeholder values for $.name, $.title, $.abstract, $.keywords, and $.highlights keys with your project’s information. You can also remove the $.name key altogether, and PyPackIT will use your repository name instead.

3. Commit and push your changes. If you have followed the link in step 1 above, you should be on the github.dev web-based editor, where you can commit and push your changes by clicking the icon in the left sidebar, typing a commit message, and clicking the Commit & Push button.

After pushing your changes, the workflow will run again. You can see the results of each job in the respective workflow run page under the repository’s Actions tab, where all created artifacts are uploaded along with comprehensive job reports and logs. Navigating to different parts of your project, you can also verify the changes made. For example:

• Under the About section of your repository’s homepage you can see the updated title, keywords, license, citation, and other project metadata, along with a link to your online documentation website.

• Looking at the changed files in the newly created commits, you can find all the files that have been updated, such as the repository README file.

• Navigating to the Releases section of your repository, you can find the draft release that is automatically updated after each push.

• In the Packages section of your repository, you can find the uploaded docker image.

• Clicking on the Binder badge in your repository README, you can verify that the docker image is now available on mybinder.org.

• If you have activated Anaconda, Zenodo, or Zenodo Sandbox, you can see the updated draft on the respective websites.

You can continue customizing your project by modifying the control center files and pushing your changes to the repository. For example, open the .control/doc.yaml file and change your project theme’s colors under $.color; this will update the color of multiple components in your website, README files, and other documents. You can also add your project’s logo by replacing the sample logo files in docs/website/source/_media/logo. If you already have some initial source code, documentation, or other resources that you want to add to your repository, you can do so now.

Control Center Configurations

PyPackIT is highly customizable with a wide range of options available in the control center, most of which are provided with standard default values based on best practices. To avoid overwhelming you with all the available options at once, only the most essential configurations are provided in the configuration files. For a full reference of all available options you can set in your repository’s control center, see the Options section.

1.1.3. Project Initialization

After you feel satisfied with the results, you can signal PyPackIT to initialize your project via a commit. Communicating with PyPackIT through commits is done via commit message footers. This is the last part of the commit message, separated from everything above it by a pre-defined separator (cf. $.commit.config). The footer must be in standard YAML syntax, just like the control center configuration files. Depending on the ongoing event, PyPackIT looks for specific keys defined in the commit footer for instructions. During the initialization phase, PyPackIT looks for a initialize-project key in the footer of the head commit of each push event. Setting this key to true will signal the end of the initialization phase. If this key is present, PyPackIT will also look for the following keys for further customized instructions for the initialization event:

version:

string, default: 0.0.0

The version to use for the initial release. This is useful if you already have an earlier version of your project published, and want to contrinue from there. Note that this must be a valid Python public version identifier

squash:

boolean, default: true

Whether to squash all previous commits into the current commit. By default, PyPackIT rewrites the entrire Git history during initialization, merging all changes into the latest commit, so that the repository only contains the initialization commit afterwards. If you want to keep the Git history of the initialization phase, set this to false.

publish-zenodo:

boolean, default: true

Whether to publish the draft release on Zenodo.

publish-pypi:

boolean, default: true

Whether to publish the initial release on PyPI.

publish-github:

boolean, default: true

Whether to publish the draft release on GitHub.

publish-zenodo-sandbox:

boolean, default: true

Whether to publish the draft release on Zenodo Sandbox.

publish-testpypi:

boolean, default: true

Whether to publish the initial release on TestPyPI.

For example, to initialize your project with version 1.0.0 while keeping all commits, use a commit message like the following:

Code 1.1.3.1 Example initialization commit message

init: Initialize my project.

Here is an optional body for my commit message.

---
initialize-project: true
version: 1.0.0
squash: false

After performing the same tasks as in the initialization phase, PyPackIT will tag the latest commit with the given version number, and publish your package to the specified repositories. It will also apply all specified branch and tag protection rulesets. Your repository is now fully configured, your package is published, your website is live, and all your workflows are set up and running.

What’s Next

Continue to the Quickstart section to learn how to start the development of your project with PyPackIT.