Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
158 lines (118 loc) · 9.17 KB

DEVELOPMENT.md

File metadata and controls

158 lines (118 loc) · 9.17 KB

Development Guide

Fork setup

Step Command Line Additional Information
1. Fork the repository -- Fork Link
2. Create a PAT for your forked repository -- See PAT setup instructions
3. Update your forked repository settings to match RepoAuditor's defaults -- --

Local Development

Enlistment

Step Command Line Additional Information
1. Clone the repository locally. git clone https://github.com/gt-sse-center/RepoAuditor git-clone docs
2. Install uv. curl -LsSf https://astral.sh/uv/install.sh | sh on macOS and Linux or
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" on Windows		 https://docs.astral.sh
3. Install dependencies. uv sync Astral uv sync docs
4. Install pre-commit hooks uv run pre-commit install Install pre-commit
5. If you wish to test against an enterprise server, add a remote named enterprise with the corresponding URL E.g. git remote add enterprise git@github.gatech.edu:sse-center/RepoAuditor.git

Setup

Basic Setup

Please follow these steps to allow for local testing.

  • Fork the RepoAuditor repository. We will test against the fork since your generated PAT is applicable only for the fork.
  • Create a PAT file as detailed in the README.
  • Set your forked repository as the origin remote (this should already be the case but it's good to verify).
git remote add origin git@github.com:<github-username>/RepoAuditor.git
  • Update the URL in default_config.yaml to point to your fork.
  • You should now be able to run the following and see valid output. There will be errors, which we will tackle next.
uv run RepoAuditor --config default_config.yaml --GitHub-pat PAT.txt

Local Testing

You can now run local tests from the project root directory with

uv run pytest -k 'not EndToEndTest'

End-To-End Testing

To include tests against your RepoAuditor fork for comprehensive end-to-end testing, you can run:

uv run pytest

In order to run end-to-end tests, which make calls to the GitHub API, you need to configure your forked repository, else you will see a large number of test failures.

Please follow the steps below to complete the configuration.

  • On the General settings page

    • Under Features
      • Check Wikis.
      • Check Issues.
      • Check Projects.
    • Under Pull Requests
      • With Allow merge commits, set the Default commit message to Pull request title.
      • Uncheck Allow squash merging.
      • Uncheck Allow rebase merging.
      • Check Allow auto-merge.
      • Check Automatically delete head branches.

  • On the Branches settings page

    • Click Add classic branch protection rule.
    • Under Branch name pattern, type in main.
    • Check Require a pull request before merging.
    • Check Require a pull request before merging -> Require approvals.
    • Check Require a pull request before merging -> Dismiss stale pull request approvals when new commits are pushed.
    • Check Require a pull request before merging -> Require approval of the most recent reviewable push.
    • Under Protect matching branches
      • Check Require status checks to pass before merging.
      • Check Require status checks to pass before merging -> Require branches to be up to date before merging.
      • Add the CI+CD Workflow / Validate (ubuntu-latest, 3.13) or an equivalent status check.
    • Check Require conversation resolution before merging.
    • Check Require signed commits.
    • Check Do not allow bypassing the above settings.

  • On the Advanced Security settings page

    • Enable Dependabot security updates.

  • Go to the Actions tab

    • Enable Workflows by clicking on I understand my workflows, go ahead and enable them.
    • Run the CI+CD workflow. You will be asked to enable it, please do so.
    • In the Run workflow dropdown to the right, click the Run workflow button. This should cause the action to run, don't worry if it fails, it is only needed for a check below.

  • On the Rules -> Rulesets settings page, create a new branch ruleset called main:

    • Under Target branches, click Add target -> Include by pattern and type in main. Finalize by clicking Add Inclusion pattern.
    • Enable Restrict deletions
    • Enable Require signed commits
    • Enable Require a pull request before merging with 1 required approval.
      • Enable Dismiss stale pull request approvals when new commits are pushed.
      • Enable Require approval of the most recent reviewable push.
      • Enable Require conversation resolution before merging.
    • Enable Require status checks to pass.
      • Enable Require branches to be up to date before merging.
      • Set the CI+CD Workflow / Validate (ubuntu-latest, 3.12) or an equivalent check.
    • Enable Block force pushes.
    • Be sure to hit Save changes at the end.

Development Activities

Activity Command Line Description Used During Local Development Invoked by Continuous Integration
Code Formatting uv run ruff format or
uv run ruff format --check		 Format source code using ruff based on settings in pyproject.toml. ✅ ✅ (via pre-commit)
Sort Imports uv run ruff check --fix --select I Sort imports in source files. ✅
Static Code Analysis uv run ruff check Validate source code using ruff based on settings in pyproject.toml. ✅ ✅ (via pre-commit)
Run pre-commit scripts uv run pre-commit run Run pre-commit scripts based on settings in .pre-commit-config.yaml. ✅ ✅
Automated Testing uv run pytest or
uv run pytest --no-cov		 Run automated tests using pytest and extract code coverage using coverage based on settings in pyproject.toml. ✅ ✅
Semantic Version Generation uv run python -m AutoGitSemVer.scripts.UpdatePythonVersion ./src/RepoAuditor/__init__.py ./src Generate a new Semantic Version based on git commits using AutoGitSemVer. Version information is stored in ./src/RepoAuditor/__init__.py. ✅
Python Package Creation uv build Create a python package using uv based on settings in pyproject.toml. Generated packages will be written to ./dist. ✅
Sign Artifacts uv run --with py-minisign python -c "import minisign; minisign.SecretKey.from_file(<temp_filename>).sign_file(<filename>, trusted_comment='<package_name> v<package_version>', drop_signature=True) Signs artifacts using py-minisign. Note that the private key is stored as a GitHub secret. ✅
Python Package Publishing uv publish Publish a python package to PyPi using uv based on settings in pyproject.toml. ✅

Contributing Changes

Pull requests are preferred, since they are specific. For more about how to create a pull request, see this guide.

We recommend creating different branches for different (logical) changes, and creating a pull request into the main branch when you're done. For more information on creating branches, please see this GitHub guide.

Verifying Signed Artifacts

Artifacts are signed and validated using py-minisign and the public key in the file ./minisign_key.pub.

To verify that an artifact is valid, visit the latest release and download the .minisign signature file that corresponds to the artifact, then run the following command, replacing <filename> with the name of the artifact to be verified:

uv run --with py-minisign python -c "import minisign; minisign.PublicKey.from_file('minisign_key.pub').verify_file('<filename>')"

Generating Documentation

We use MkDocs to generate the documentation website. To generate the docs, please run

uv run mkdocs serve

and go to the specified URL.

To publish the website using GitHub pages, you can simply run

uv run mkdocs gh-deploy