Skip to content

Latest commit

 

History

History
115 lines (77 loc) · 4.08 KB

CONTRIBUTING.md

File metadata and controls

115 lines (77 loc) · 4.08 KB

Contributing to starbridge

Thank you for considering contributing to starbridge!

Development Environment Setup

Clone this GitHub repository via git clone [email protected]:helmut-hoffer-von-ankershoffen/starbridge.git and change into the directory of your local starbridge repository: cd starbridge

Install the dependencies:

macOS

if ! command -v brew &> /dev/null; then # if Homebrew package manager not present ...
  /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # ... install it
else
  which brew # ... otherwise inform where brew command was found
fi
# Install required tools if not present
which jq &> /dev/null || brew install jq
which xmllint &> /dev/null || brew install xmllint
which act &> /dev/null || brew install act
uv run pre-commit install             # install pre-commit hooks, see https://pre-commit.com/

Linux

Notes:

  • Not yet validated
  • .github/workflows/test.yml might provide further information
sudo sudo apt install -y curl jq libxml2-utils libcairo2 gnupg2 npm  # tooling
curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash # act
uv run pre-commit install                   # see https://pre-commit.com/

Configuration

You can use the following helper command to create the .env file. This will prompt you for the required configuration values.

uv run starbridge configure # creates .env file

You can validate starbridge is working correctly by checking the health endpoint

uv run starbridge health # shows healtiness of starbridge including dependencies

To see all commands starvridge offers you can call uv run starbridge --help

Debugging

Inspect starbridge using the MCP inspector

uv run starbridge mcp inspect

Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging. Environment values are loaded from the .env file generated in the previous step

Installing the development version of starbridge with Claude Desktop application

You can use the following helper command to install the development version of starbridge with Claude Desktop application. This will amend the configuration file of Claude Desktop to reference your local repository, and restart Claude Desktop.

uv run starbridge install

Code and configuration changes

For the Claude Desktop app to pick up code changes to starbridge restart the Claude Desktop application with uv run starbridge claude restart.

If you added additional configuration keys in .env.template, run uv run starbridge configure again, to update the .env file. After that run uv run starbridge install to install the updated configuration with the Claude Desktop application.

To show the configuration of starbridge within Claude, you can use uv run starbridge claude config.

Running all build steps

All build steps are defined in noxfile.py.

uv run nox

You can run individual build steps - called sessions in nox as follows:

uv run nox -s test      # run tests
uv run nox -s lint      # run formatting and linting
uv run nox -s audit     # run security and license audit, inc. sbom generation
uv run nox -s docs      # build documentation, output in docs/build/html

Running GitHub CI workflow locally

Notes:

  • Workflow defined in .github/workflows/ci.yml
  • Calls all build steps defined in noxfile.py
./github-action-run.sh

Pull Request Guidelines

  • Pre-Commit Hooks: We use pre-commit hooks to ensure code quality. Please install the pre-commit hooks by running uv run pre-commit install. This ensure all tests, linting etc. pass locally before you can commit.
  • Squash Commits: Before submitting a pull request, please squash your commits into a single commit.
  • Branch Naming: Use descriptive branch names like feature/your-feature or fix/issue-number.
  • Testing: Ensure new features have appropriate test coverage.
  • Documentation: Update documentation to reflect any changes or new features.