starbase

The base repository for Starcraft projects.

Description

This template code is the basis for all future starcraft projects, and acts as the testbed for any major tooling changes that we want to make before propagating them across all projects.

Structure

TODO

Migrate existing projects

1. Update this guide as you go along, if something is unclear or missing.

2. Use ruff. #. Pull in the bare minimum pyproject.toml needed to use ruff. #. Make your codebase pass with ruff. Commit after each step:

   1. ruff check --fix
   2. ruff check --fix --unsafe-fixes
   3. ruff check --add-noqa
   4. ruff format

   1. Replace use of black, flake8, pydocstyle, isort, and pylint in Makefile/CI with: - ruff check --fix - ruff format

3. Modify top-level files in your project to match what's in Starbase as closely as possible. #. Makefile - Ensure you use uv and at least have the same targets:

   • setup
   • lint
   • test-unit
   • test-integration (If this applies to your repo, i.e. the repo is a library rather than an application)
   • coverage

   1. pyproject.toml - Expand from just the ruff things: move things into here from your setup.py, setup.cfg, and requirements.*.txt.
   2. README - If your readme is .md, convert to .rst with pandoc: pandoc -o README.rst README.md Don't worry about making the contents match, Starbase's is very specific.

4. Run all the linters: make lint #. mypy:

   • Mypy checks the same things as ruff's ANNXXX checks, but ruff's noqa directives mean nothing to mypy. You'll need to fix these by hand, mostly by adding type annotations to function definitions.

   1. pyright:
      • For errors along the lines of "Stub file not found for $library", check for the existence of pip package typing-$library and add it as a dependency.
      • If you have lots of errors you may need to remove the strict directive from pyproject.toml.

5. Do a side-by-side diff of the .gitignore files in your project and Starbase, making them as close as possible and adding anything that makes sense upstream.

6. Bring in remaining top-level files: - .editorconfig - .pre-commit-config.yaml - .shellcheckrc - tox.ini - .yamllint.yaml

7. If you're rebasing a library, add the integrations tests structure. Applications should use spread for integration tests.

8. Finally, once all files are manually synced, actually sync the git history:

   • git remote add starbase [email protected]:canonical/starbase.git
   • git merge --allow-unrelated-histories starbase/main
   • git remote remove starbase
   • Don't forget to review all the new files and dirs that this merge adds - you'll want to delete a lot of them.
   • When you merge, DO NOT squash, otherwise the starbase history will not be preserved.

Create a new project

1. Use this template to create your repository.
2. Sync the git history with starbase to ease future merging: - git clone <your-repo> - git remote add starbase [email protected]:canonical/starbase.git - git merge --allow-unrelated-histories starbase/main - git push -f origin main - git remote remove starbase
3. Ensure the LICENSE file represents the current best practices from the Canonical legal team for the specific project you intend to release. We use LGPL v3 for libraries, and GPL v3 for apps.
4. Rename any files or directories and ensure references are updated.
5. Replace any instances of the words Starcraft and starbase with the product's name.
6. Place contact information in a code of conduct.
7. Rewrite the README.
8. If a Diataxis quadrant (tutorials, how-tos, references, explanations) doesn't yet have content, remove its landing page from the TOC and delete its card in docs/index.rst. You can re-index it when at least one document has been produced for it.
9. Register the product's documentation on our custom domain on Read the Docs for Business.