mirror of
https://github.com/NCBM/plyngent.git
synced 2026-07-23 05:55:16 +08:00
61 lines
2.6 KiB
Markdown
61 lines
2.6 KiB
Markdown
|
# Development Principles
|
||
|
|
|
||
|
|
## If you are new to project
|
||
|
|
|
||
|
|
### Have a general overview of the project
|
||
|
|
|
||
|
|
You should at least have a clear view of the general architecture. This aims for:
|
||
|
|
|
||
|
|
1. keeping the style of codebase consistent.
|
||
|
|
2. using or extending existing objects or functions instead of writing new but duplicate code, since the latter is usually a kind of **SHIT**.
|
||
|
|
|
||
|
|
For a general architecture reference, see [here](./architecture.md).
|
||
|
|
|
||
|
|
This does not mean you should immediately grasp the whole codebase, but **you should not make changes until you have a clear view of the general architecture**.
|
||
|
|
|
||
|
|
### Commit messages
|
||
|
|
|
||
|
|
This project uses scoped commit message. Examples:
|
||
|
|
|
||
|
|
- `project: init`: initializing a new project.
|
||
|
|
- `deps: add fastapi`: add/upgrade/removing a dependency.
|
||
|
|
- `deps/dev: upgrade ruff`: add/upgrade/removing a dev dependency.
|
||
|
|
- `core/mq: fix incorrect message sending`, `router: add routing service for xxx`: add/change/fix/refactor/removing functional code.
|
||
|
|
- `test/webserver: change test client to niquests`: add/change/fix/refactor/removing tests.
|
||
|
|
- `scripts/i18n: implement dumping translation keys`: add/change/fix/refactor/removing general scripts.
|
||
|
|
- `ci/lint: run ruff style check`, `ci/build: fix changelog generation`: add/change/fix/refactor/removing CI workflows.
|
||
|
|
|
||
|
|
Once conventional commit was good, until redundant forms like `fix: fix ...`, `refactor: refactor ...` came up. So we use scoped commit message here.
|
||
|
|
|
||
|
|
If you are still not quite familiar to this, check the git log in any way you prefer.
|
||
|
|
|
||
|
|
## General information and suggestions
|
||
|
|
|
||
|
|
### Local development environment
|
||
|
|
|
||
|
|
Syncing packages: `pdm install` the first time, then `pdm sync`. The former can fully initialize the dependencies, and the latter can continuously keep consistent dependencies.
|
||
|
|
|
||
|
|
For other commands like adding or removing packages, see [PDM Documentation](https://pdm-project.org/en/latest/usage/dependency/). These commands usually updates lock file automatically by default, so `pdm sync` should only be used when after `git pull/fetch/checkout`.
|
||
|
|
|
||
|
|
### Type checking and linting
|
||
|
|
|
||
|
|
Firstly, we prefer using `pdm run <command/script>` to directly running commands in venv (whether in activated environment or not).
|
||
|
|
|
||
|
|
Then for every projects, check the dev dependency group where you can find tools used for type checking and linting.
|
||
|
|
|
||
|
|
Type checking: `pdm run basedpyright .`
|
||
|
|
Linting: `pdm run ruff check .`
|
||
|
|
Formating: `pdm run ruff format .`
|
||
|
|
|
||
|
|
<!-- Contents in comments are for projects with long-period developments, but this is a new project.
|
||
|
|
|
||
|
|
### Branches
|
||
|
|
|
||
|
|
In most cases, we do not need and should not make bare commits on the main branch.
|
||
|
|
|
||
|
|
### Tests
|
||
|
|
|
||
|
|
...
|
||
|
|
|
||
|
|
-->
|