Package Maintenance

Package Maintenance#

This page is intended for developers working on OverleafFS. It summarizes how the package is built and published, and how the GitHub–PyPI link is configured.

Overview#

OverleafFS is packaged as a standard Python project using pyproject.toml and setuptools. The project can be installed locally with pip, and new releases are published to PyPI using a GitHub Actions workflow together with PyPI’s Trusted Publisher integration.

In normal day-to-day work you will:

  • Bump the version in pyproject.toml

  • Commit and push changes to the main repository

  • Tag a release (e.g. v0.1.1)

  • Create a GitHub Release for that tag

The GitHub Actions workflow then builds and uploads the package to PyPI without requiring local credentials.

Local Installation and Testing#

Before publishing a new release, it is a good idea to test a local install from the current source tree.

From the repository root:

# optional: create/activate a virtual environment
python -m pip install --upgrade pip

# install the package in editable mode
pip install -e .

# run the GUI
overleaf-fs

You can also build the distribution artifacts locally:

python -m pip install --upgrade build
python -m build

This will create dist/ containing a source distribution (.tar.gz) and a wheel (.whl). These are the same types of artifacts that will be uploaded to PyPI by the GitHub workflow.

Release Workflow#

The release process is driven by Git tags and GitHub Releases. The high-level steps for making a new release are:

  1. Choose a new version number. Use semantic versioning, e.g. 0.1.1.

  2. Update ``pyproject.toml``.

    In the [project] section, set:

    name = "overleaf_fs"
version = "X.Y.Z"

    where X.Y.Z is the chosen version.

  3. Commit and push.

    git add pyproject.toml
git commit -m "Bump version to X.Y.Z"
git push

  4. Create a tag and push it.

    Tags are typically of the form vX.Y.Z:

    git tag vX.Y.Z
git push origin vX.Y.Z

  5. Create a GitHub Release.

    • Go to the Releases page in the GitHub repository

    • Click “Draft a new release”

    • Select the tag (e.g. vX.Y.Z)

    • Give the release a title and (optionally) release notes

    • Click Publish release

This final step triggers the GitHub Actions workflow that builds and publishes the new version to PyPI.

GitHub–PyPI Integration (Trusted Publisher)#

Publishing is handled by a GitHub Actions workflow configured as a Trusted Publisher on PyPI (see https://pypi.org/manage/account/publishing/). This avoids storing long-lived API tokens in secret and instead uses short-lived credentials obtained via OpenID Connect (OIDC).

Workflow location#

The publishing workflow lives at:

.github/workflows/publish.yml

The workflow:

  • Runs when a GitHub Release is published (and can also be run manually)

  • Checks out the repository

  • Installs Python and the build tool

  • Builds the wheel and source distribution via python -m build

  • Uses pypa/gh-action-pypi-publish to upload to PyPI

The key portion of the workflow looks like:

on:
  release:
    types: [published]
  workflow_dispatch:

jobs:
  build-and-publish:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install build tooling
        run: |
          python -m pip install --upgrade pip
          pip install build

      - name: Build distributions
        run: python -m build

      - name: Publish to PyPI
        uses: pypa/gh-action-pypi-publish@release/v1

PyPI Trusted Publisher setup#

On the PyPI side, the project overleaf_fs is configured to trust this GitHub workflow as a publisher:

  • Log in to PyPI and go to Account → Publishing

  • Add a new pending publisher with:

    • Project name: overleaf_fs

    • Provider: GitHub

    • Owner: the GitHub user or organization that owns the repository

    • Repository: the repository name

    • Workflow filename: .github/workflows/publish.yml

    • Environment: left blank (no explicit GitHub environment is used)

  • After the workflow runs successfully for the first time from the configured repository and workflow file, PyPI recognizes it as a Trusted Publisher and associates it with the project.

Once this is set up, future releases do not require API tokens or manual twine commands.

Troubleshooting#

A few common issues and checks:

  • Version already exists on PyPI

    If the workflow fails with an error about an existing version, make sure you bumped version in pyproject.toml and created a new tag (e.g. v0.1.2).

  • Workflow not triggered

    Ensure that a GitHub Release was actually published for the tag. The workflow triggers on release: [published], not just on pushing a tag.

  • Trusted Publisher mismatch

    If PyPI rejects the upload with an authorization error, verify that:

    • The project name on PyPI is overleaf_fs

    • The repository owner, name, and workflow filename on the PyPI Publishing page match the actual GitHub repository and .github/workflows/publish.yml

    • The workflow has permissions: id-token: write

  • Local vs installed behavior

    If you see different behavior between a locally installed editable version (pip install -e .) and the PyPI release, confirm that all relevant changes have been committed, tagged, and that you are installing the expected version from PyPI when testing.

This page should be updated as the release process evolves (for example, if additional checks, tests, or deployment steps are added).

Contents