diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 00000000..1705d1bd --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,7 @@ +version: 2 +updates: + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + open-pull-requests-limit: 10 diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index fa5c6847..ee95fb6b 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -1,36 +1,58 @@ name: Build and deploy the Starterkit lessons website. -on: push + +on: + push: + branches: + - master + pull_request: + workflow_dispatch: + +concurrency: + group: lessons-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + jobs: build: runs-on: ubuntu-latest + permissions: + contents: read steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v6 + - name: Set up Python - uses: actions/setup-python@v2 + uses: actions/setup-python@v6 with: - python-version: 3.13.1 - - name: Install dependencies - run: pip install -vv starterkit-ci>=0.1.0 + python-version: "3.13" + + - name: Install uv + uses: astral-sh/setup-uv@v7 + - name: Build the website - run: starterkit_ci build --allow-warnings + run: uvx starterkit-ci build --source-dir . --allow-warnings + - name: Check for dead links - run: starterkit_ci check --allow-warnings + run: uvx starterkit-ci check --source-dir . --allow-warnings + - name: Upload build artifacts - uses: actions/upload-artifact@v4 + uses: actions/upload-artifact@v6 with: name: build path: build/html/ + deploy: - if: ${{ github.ref == 'refs/heads/master' }} + if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }} runs-on: ubuntu-latest needs: build + permissions: + contents: write steps: - name: Download build artifacts - uses: actions/download-artifact@v4 + uses: actions/download-artifact@v7 with: name: build + - name: Deploy - uses: peaceiris/actions-gh-pages@v3 + uses: peaceiris/actions-gh-pages@v4 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: . diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fa45fde0..e1bf786a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,34 +15,44 @@ You also agree to abide by our [contributor code of conduct][conduct]. 1. We use the [fork and pull][gh-fork-pull] model to manage changes. More information about [forking a repository][gh-fork] and [making a Pull Request][gh-pull]. -2. To build the lessons please install the [dependencies](#DEPENDENCIES). +2. To build and check the lessons locally, follow [Dependencies and local checks](#dependencies-and-local-checks). -2. For our lessons, you should branch from and submit pull requests against the `master` branch. +3. For our lessons, you should branch from and submit pull requests against the `master` branch. -3. When editing lesson pages, you need only commit changes to the Markdown source files. +4. When editing lesson pages, you need only commit changes to the Markdown source files. -4. If you're looking for things to work on, please see [the list of issues for this repository][issues]. +5. If you're looking for things to work on, please see [the list of issues for this repository][issues]. Comments on issues and reviews of pull requests are equally welcome. -## Dependencies +## Dependencies and local checks -To build the lessons locally, install the following: +The CI workflow builds and link-checks this repository using `starterkit-ci`. +Use the same commands locally before opening a PR. -1. [starterkit-ci](https://pypi.org/project/starterkit-ci/) +### Option A: run without installing (recommended) -Then build the pages: +```shell +uvx starterkit-ci build --source-dir . --allow-warnings +uvx starterkit-ci check --source-dir . --allow-warnings +``` + +### Option B: install the tool first ```shell -$ starterkit_ci build --allow-warnings -$ starterkit_ci check --allow-warnings +pip install starterkit-ci +starterkit-ci build --source-dir . --allow-warnings +starterkit-ci check --source-dir . --allow-warnings ``` -and start a web server to host them: +Note: `starterkit_ci` (underscore) is still accepted as a legacy alias, but `starterkit-ci` is the preferred command. + +To preview the generated docs locally, start a web server: ```shell -$ cd build -$ python -m http.server 8000 +cd build +uv run python -m http.server 8000 ``` + You can see your local version by using a web-browser to navigate to `http://localhost:8000` or wherever it says it's serving the book. [conduct]: CONDUCT.md