First of all, thank you for wanting to contribute to dicognito! We really appreciate any support we get from our community. We want to keep it as easy as possible for you to contribute changes that make dicognito better for you. There are a few guidelines that we need contributors to follow so that we can all work together happily.
Before starting work on a functional change, like a new feature, a change to an existing feature, or a bug fix, please ensure an issue has been raised. Indicate your intention to work on the issue by writing a comment against it. This will prevent duplication of effort. If the change is non-trivial, it's usually best to propose a design in the issue comments.
It is not necessary to raise an issue for non-functional changes such as refactoring, adding tests, reformatting code, documentation, updating packages, etc.
Changes in functionality (new features, changed behavior, or bug fixes) should be described by new or updated tests.
We use Ruff as linter and formatter. Please follow existing conventions. Any deviations will cause the build to fail.
Dicognito uses the git branching model known as GitHub flow.
As such, all development must be performed on a
"feature branch" created from the main development
branch, which is called main. To submit a change:
- Fork the dicognito repository on GitHub
- Clone your fork locally
- Configure the upstream repo (
git remote add upstream git://github.com/blairconrad/dicognito.git) - Create a local branch (
git checkout -b my-branch main) - Work on your feature
- Rebase if required (see "Handling Updates from upstream/main" below)
- Ensure the build and tests succeed (see "How to build")
- Push the branch up to GitHub (
git push origin my-branch) - Send a pull request on GitHub
You should never work directly on the main branch and you should never send a pull request from
the main branch - always from a feature branch.
While you're working away in your branch it's quite possible that your upstream/main (most likely the canonical dicognito version) may be updated. If this happens you should:
- Stash any un-committed changes you need to
git checkout maingit pull upstream maingit checkout my-branchgit rebase main my-branchgit push origin main- (optional) this makes sure your remote main branch is up to date- if you previously pushed your branch to your origin, you need to force push the rebased branch -
git push origin my-branch --force-with-lease
This ensures that your history is "clean". That is, you have one branch off from main followed by your changes in a straight line. Failing to do this ends up with several "messy" merges in your history, which we don't want. This is the reason why you should always work in a branch and you should never be working in, or sending pull requests from, main.
If you're working on a long-running change then you may want to do this quite often, rather than run the risk of potential large merge conflicts further down the line.
While working on your feature you may well create several branches, which is fine, but before you send a pull request you should ensure that you have rebased back to a single feature branch. We care about your commits and we care about your feature branch but we don't care about how many or which branches you created while you were working on it. 😄
When you're ready to go you should confirm that you are up to date and rebased with upstream/main (see "Handling Updates from upstream/main" above) and then:
git push origin my-branch- Send a pull request in GitHub, selecting the following dropdown values:
| Dropdown | Value |
|---|---|
| base fork | blairconrad/dicognito |
| base | main |
| head fork | {your fork} (e.g. {your username}/dicognito) |
| compare | my-branch |
The pull request should include a description starting with "Fixes #12345." (using the real issue number, of course) if it fixes an issue. If there's no issue, be sure to clearly explain the intent of the change.