Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
127 lines (102 loc) · 5.55 KB

CONTRIBUTING.md

File metadata and controls

127 lines (102 loc) · 5.55 KB

Contributing

Contributions are welcome! Make sure to first open an issue discussing the problem or the new feature before creating a pull request. This project uses uv to manage development dependencies and npm to manage workflow dependencies.

Set Up Development Environment

Python and nodejs is used for development. These must be installed before contributing to the project.

Install Python with uv

Since this project uses uv for development, the easiest way to install both is to install uv on your machine. Then you can use uv to install Python if not yet installed on your machine.

uv python install 3.13

Install NodeJS

NodeJS can be installed for all systems from their website.

Install Dependencies

Once nodejs is installed, the workflow dependencies can be installed with the following command

npm install

This command should be run in all folders that have a package.json file. Each folder prepended with peerstash- is essentially a subproject.

Once uv is installed, the development dependencies can be installed in the peerstash-control folder using the following command

uv sync

Development Deployment

To deploy this project, use the docker-compose-dev.yml file. A .env file must be created to fill out certain fields. An example environment file can be found in the peerstash-compose folder. If environment variables aren't working, the fields can be manually replaced in the docker compose file.

docker compose -f peerstash-compose/docker-compose-dev.yml up

Tailscale Tunnel

Tailscale needs access to the network tunnel device. The docker compose file has the host device hardcoded to the same path (/dev/net/tun:/dev/net/tun), but this appears to be valid only on linux systems. If you know how to make this work on non-linux systems please make an issue and/or pull request.

Dev Tools

There are dev tools available in the peerstash-control folder to check the code for syntax errors and other potential issues.

Python

pyright is used to check for errors in Python files.

cd peerstash-control
uv run pyright

black and isort are used for formatting to keep files consistent.

cd peerstash-control
uv run black
uv run isort

pytest can be used within the peerstash-control folder to run unit tests.

cd peerstash-control
pytest

There are two scripts in the top-level scripts folder that runs tests in a docker container. run_docker_tests.sh runs integration tests. run_all_tests.sh runs all tests in a docker container and generates a coverage report in peerstash-control/htmlcov.

bash scripts/run_docker_tests.sh

Shell Checks

The shellcheck node module is used to check for POSIX compliance in shell scripts. Running the command below should output nothing to the terminal if all scripts are compliant with POSIX.

cd peerstash-control
npx shellcheck scripts/*.sh

Commits

When committing code, follow the Conventional Commit style for writing commit messages:

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

Examples

  • feat(control): create setup script
  • fix(compose): hardcode SFTPGo port
  • feat(control,compose): add SFTPGo config folder as read-only bind mount in control container

Types

The type is used to determine the version bump. Only one should be used per commit message. The types used have been adapted from angular:

type [version]: description

  • feat [minor]: A new feature
  • fix [patch]: A bug fix
  • perf [patch]: A code change that improves performance
  • docs: Documentation only changes
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  • refactor: A code change that neither fixes a bug nor adds a feature
  • test: Adding missing or correcting existing tests
  • chore: Changes to the build process or auxiliary tools and libraries such as documentation generation

Scopes

The scope is used to determine the service that was changed to allow for separate versions of each service. Multiple can be used per commit message.

scope: description

REQUIRED (if changed)

  • control: peerstash-control was updated
  • compose: peerstash-compose/docker-compose.yml was updated

Other

  • ci: changes to the workflows were made
  • release: used by semantic-release when an update is made
  • README: changes to the readme were made
  • CONTRIBUTING: changes to the contributing file were made
  • LICENSE: changes to the license were made

Extras

  • The start of <body> or <footer> can be BREAKING CHANGE: to indicate a major version bump
  • Keep each line under 100 characters

Versioning

This project follows the semantic versioning format for versioning:

  • major reserved for breaking changes (needs maintainer approval)
  • minor for new features and larger tweaks (usually changing user experience like adding an option to the config)
  • patch for bug fixes and smaller tweaks (usually doesn't affect user experience)

The commit type indicates whether a bump should be patch or minor. The version will be updated automatically based on the commit.