Skip to content

Contributing

The guide is modified from mkdocstrings

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

Environment setup

First, fork and clone the repository, then cd to the directory.

Note

Note that we have a submodule in this repository, so you need to use --recurse-submodules to clone it.

# https://git-scm.com/book/en/v2/Git-Tools-Submodules
git clone --recurse-submodules https://github.com/WSH032/aria2-server-gui.git

cd aria2-server-gui

We use hatch and pre-commit to manage our project.

You can install them with:

# https://pypa.github.io/pipx/
python3 -m pip install --user pipx

pipx install hatch
pipx install pre-commit

Note

check requirements.txt to know the version of hatch and pre-commit we use.

Then, initialize the env with:

# https://hatch.pypa.io/latest/environment/
# IMPORTANT: Create hatch venv before running pre-commit
hatch env create default
hatch env create fmt
hatch env create docs

# IMPORTANT: init pyright-python before running pre-commit
#     issue: https://github.com/RobertCraigie/pyright-python/issues/200
hatch run default:pyright --help

# Init pre-commit
# https://pre-commit.com/#3-install-the-git-hook-scripts
pre-commit install
pre-commit run --all-files

# enter the dev environment
hatch shell default

That's all! Now, you can start to develop.

Code style

The source code is in src/

We use Ruff, Pyright and Codespell to format, lint our code and type check.

Please check pyproject.toml to know our style.

If you want to format your code, you can use the following command:

hatch run fmt:fmt
hatch run fmt:spell-fix

or, dry run to check:

hatch run fmt:fmt-check

If you want to perform type checking, you can use the following command:

hatch run type-check

Tip

If you use VSCode, we strongly recommend you to install the extensions in .vscode/extensions.json.
Because our code style rules are quite strict.
These extensions can help you know where need to be fixed when coding.

Testing

We use pytest to test our code.

The test source code is in tests/

You can run the testing with:

hatch run test

Documentation

We use mkdocs, mkdocs-material, mkdocstrings to build our documentation.

The documentation source code is in docs/, mkdocs.yml, may be there is also some source code in scripts/ or somewhere (check mkdocs.yml to find that).

Live-reloading docs:

hatch run docs:mkdocs serve

Build docs:

hatch run docs:build

mkdocs reference

Tip

Code Docstring styles

Warning

We use Google style to write docstrings, please refer to

PR

  • PRs should target the main branch.
  • Keep branches up to date by rebase before merging.
  • Do not add multiple unrelated things in same PR.
  • Do not submit PRs where you just take existing lines and reformat them without changing what they do.
  • Do not change other parts of the code that are not yours for formatting reasons.
  • Do not use your clone's main branch to make a PR - create a branch and PR that.

Edit CHANGELOG.md

If you have made the corresponding changes, please record them in CHANGELOG.md.

Commit message convention

Commit messages must follow Conventional Commits, or, pre-commit may be reject your commit.

Info

If you don't know how to finish these, it's okay, feel free to initiate a PR, I will help you continue.

More

There may still be some useful commands in pyproject.toml, you can refer to hatch/environment/scripts to use them.

Info

If you find that the commands given in the above examples are incorrect, please open an issue, we greatly appreciate it.

😢

Warning

The following 👇 content is for the maintainers of this project, may be you don't need to read it.

deploy-docs

please refer to .github/workflows/docs.yml

CI: lint-test

please refer to .github/workflows/lint-test.yml

Publish and Release 🚀

First, check-out to a new branch, edit CHANGELOG.md to record the changes.

Then, please refer to:

Update version in new branch with:

git add .
hatch version {new_version}

It will create a commit and tag automatically.

Then, push the new branch with tag to GitHub, and create a PR to main branch.

Warning

The bump version PR must have only one commit with the corresponding tag; otherwise, it will be rejected.

Review the PR, if it's ok, rebase it to main branch in local

Warning

DO NOT rebase with tag in GitHub, refer to https://docs.github.com/zh/authentication/managing-commit-signature-verification/about-commit-signature-verification#signature-verification-for-rebase-and-merge

Check if everything is ok, for example:

  • check if the tag is on the main branch.
  • check if the link in CHANGELOG.md is correct.

If so, make a approve in environment pypi for the workflow.

After that, the publish.yml workflow will build and publish the package to PyPI.

Finally, edit the draft release created by publish.yml workflow, and publish the release.

Warning

The creating of tag needs signature verification,
please refer to https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification