base: Initial specification for the base repository (#2)

.github/PULL_RELEASE_TEMPLATE.md

@@ -0,0 +1,5 @@
+- [ ] Have you followed the guidelines for contributing?
+- [ ] Have you signed the [CLA](http://www.ubuntu.com/legal/contributors/)?
+- [ ] Have you successfully run `tox`?
+
+-----

.github/release-drafter.yaml

@@ -0,0 +1,24 @@
+categories:
+  - title: "New Features"
+    labels:
+      - "enhancement"
+  - title: "Maintenance"
+    labels:
+      - "maintenance"
+  - title: "Bug Fixes"
+    labels:
+      - "bug"
+  - title: "Specifications and Documentation"
+    label:
+      - "specification"
+      - "doc"
+  - title: "Tooling"
+    label:
+      - "tooling"
+change-template: '- $TITLE @$AUTHOR (#$NUMBER)'
+template: |
+  Special thanks to the contributors that made this release happen: $CONTRIBUTORS
+  
+  ## Full list of changes
+
+  $CHANGES

.github/renovate.json5

@@ -0,0 +1,68 @@
+ {
+  // Configuration file for RenovateBot: https://docs.renovatebot.com/configuration-options
+  extends: ["config:base"],
+  labels: ["dependencies"],  // For convenient searching in GitHub
+  pip_requirements: {
+    fileMatch: ["pyproject.toml", "tox.ini"]
+  },
+  packageRules: [
+    {
+      // Automerge patches, pin changes and digest changes.
+      // Also groups these changes together.
+      groupName: "patch updates",
+      matchUpdateTypes: ["patch", "pin", "digest"],
+      prPriority: 3, // Patches should go first!
+      automerge: true
+    },
+    {
+      // Update all internal packages in one higher-priority PR
+      groupName: "internal packages",
+      matchPackagePrefixes: ["craft-", "snap-"],
+      matchLanguages: ["python"],
+      prPriority: 2
+    },
+    {
+      // GitHub Actions are higher priority to update than most dependencies.
+      matchManagers: ["github-actions"],
+      prPriority: 1
+    },
+    // Everything not in one of these rules gets priority 0 and falls here.
+    {
+      // Minor changes can be grouped and automerged for dev dependencies, but are also deprioritised.
+      groupName: "development dependencies (minor and patch)",
+      groupSlug: "dev-dependencies",
+      matchDepTypes: ["devDependencies"],
+      matchUpdateTypes: ["minor", "patch", "pin", "digest"],
+      prPriority: -1,
+      automerge: true
+    },
+    {
+      // Other major dependencies get deprioritised below minor dev dependencies.
+      matchUpdateTypes: ["major"],
+      prPriority: -2
+    },
+    {
+      // Major dev dependencies are stone last.
+      matchDepTypes: ["devDependencies"],
+      matchUpdateTypes: ["major"],
+      prPriority: -3
+    }
+  ],
+  regexManagers: [
+    {
+      // tox.ini can get updates too if we specify for each package.
+      fileMatch: ["tox.ini"],
+      matchStrings: [
+        "# renovate: datasource=(?<datasource>\\S+)\n\\s+(?<depName>.*?)[=><]=?(?<currentValue>.*?)\\n",
+      ]
+    }
+  ],
+  timezone: "Etc/UTC",
+  automergeSchedule: "after 1 am and before 7 am",
+  schedule: "every weekend",
+  prConcurrentLimit: 5, // No more than 5 open PRs at a time.
+  prCreation: "not-pending", // Wait until status checks have completed before raising the PR
+  prNotPendingHours: 4, // ...unless the status checks have been running for 4+ hours.
+  prHourlyLimit: 1, // No more than 1 PR per hour.
+  stabilityDays: 2 // Wait 2 days from release before updating.
+}

.github/workflows/cla-check.yaml

@@ -0,0 +1,9 @@
+name: cla-check
+on: [pull_request]
+
+jobs:
+  cla-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check if CLA signed
+        uses: canonical/has-signed-canonical-cla@v1

.github/workflows/release-drafter.yaml

@@ -0,0 +1,16 @@
+name: Release Drafter
+
+on:
+  push:
+    # branches to consider in the event; optional, defaults to all
+    branches:
+      - master
+
+jobs:
+  update_release_draft:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Release Drafter
+        uses: release-drafter/[email protected]
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/tests.yaml

@@ -0,0 +1,86 @@
+name: Tests, linting, etc.
+on:
+  push:
+    branches:
+      - "main"
+      - "feature/*"
+      - "hotfix/*"
+      - "release/*"
+  pull_request:
+
+jobs:
+  linters:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+      - name: Configure environment
+        run: |
+          echo "::group::Begin snap install"
+          echo "Installing snaps in the background while running apt and pip..."
+          sudo snap install --no-wait --classic pyright
+          sudo snap install --no-wait shellcheck
+          echo "::endgroup::"
+          echo "::group::pip install"
+          python -m pip install 'tox>=4' tox-gh
+          echo "::endgroup::"
+          echo "::group::Create virtual environments for linting processes."
+          tox run-parallel --parallel all --parallel-no-spinner -m lint --notest
+          echo "::endgroup::"
+          echo "::group::Wait for snap to complete"
+          snap watch --last=install
+          echo "::endgroup::"
+      - name: Run Linters
+        run: tox run -m lint
+  tests:
+    strategy:
+      matrix:
+        platform: [ubuntu-20.04, ubuntu-22.04]
+    runs-on: ${{ matrix.platform }}
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Set up Python versions on ${{ matrix.platform }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: |
+            3.8
+            3.9
+            3.10
+            3.11
+            3.12-dev
+      - name: Configure environment
+        run: |
+          echo "::group::pip install"
+          python -m pip install 'tox>=4' tox-gh
+          echo "::endgroup::"
+          mkdir -p results
+      - name: Setup Tox environments
+        run: >
+          tox run-parallel --parallel auto --parallel-no-spinner 
+          --parallel-live -m tests --notest
+      - name: Test with tox
+        run: > 
+          tox run-parallel --parallel all --parallel-no-spinner 
+            --skip-pkg-install 
+            --result-json results/tox-${{ matrix.platform }}.json 
+            -m tests
+            -- --no-header --quiet -rN
+      - name: Upload code coverage
+        uses: codecov/codecov-action@v3
+        with:
+          directory: ./results/
+          files: coverage*.xml
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v3
+        with:
+          name: test-results-${{ matrix.platform }}
+          path: results/

.gitignore

@@ -127,3 +127,9 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+
+# Caches for various tools
+/.*_cache/
+
+# Test results
+/results/

HACKING.rst

@@ -0,0 +1,56 @@
+*********
+Starcraft
+*********
+
+Welcome to Starcraft! We hope this document helps you get started. Before contributing any code, please sign the `Canonical contributor licence agreement`_.
+
+Setting up a development environment
+------------------------------------
+We use a forking, feature-based workflow, so you should start by forking the repository. Once you've done that, clone the project to your computer using git clone's ``--recurse-submodules`` parameter. (See more on the `git submodules`_ documentation.)
+
+Tooling
+=======
+We use a large number of tools for our project. Most of these are installed for you with tox, but you'll need to install:
+
+- Python 3.8 (default on Ubuntu 20.04, available on Ubuntu 22.04 through the deadsnakes_ PPA) with setuptools.
+- tox_ version 4 or later. (3.8+ will automatically provision a v4 virtualenv)
+- Pyright_ (it's recommended you install with ``snap install --classic pyright``)
+- ShellCheck_  (also available via snap: ``snap install shellcheck``)
+
+Once you have all of those installed, you can install the necessary virtual environments for this repository using tox.
+
+Other tools
+###########
+Some other tools we use for code quality include:
+
+- Black_ for code formatting
+- pytest_ for testing
+- ruff_ for linting (and some additional formatting)
+
+A complete list is kept in our pyproject.toml_ file in dev dependencies.
+
+Initial Setup
+#############
+
+After cloning the repository but before making any changes, it's worth ensuring that the tests, linting and tools all run on your machine. Running ``tox`` with no parameters will create the necessary virtual environments for linting and testing and run those::
+
+    tox
+
+If you want to install the environments but not run the tests, you can run::
+
+    tox --notest
+
+If you'd like to run the tests with a newer version of Python, you can pass a specific environment. You must have an appropriately versioned Python interpreter installed. For example, to run with Python 3.10, run::
+
+    tox -e test-py310
+
+.. _Black: https://black.readthedocs.io
+.. _`Canonical contributor licence agreement`: http://www.ubuntu.com/legal/contributors/
+.. _deadsnakes: https://launchpad.net/~deadsnakes/+archive/ubuntu/ppa
+.. _`git submodules`: https://git-scm.com/book/en/v2/Git-Tools-Submodules#_cloning_submodules
+.. _pyproject.toml: ./pyproject.toml
+.. _Pyright: https://github.com/microsoft/pyright
+.. _pytest: https://pytest.org
+.. _ruff: https://github.com/charliermarsh/ruff
+.. _ShellCheck: https://www.shellcheck.net/
+.. _tox: https://tox.wiki