Contribute to Dfetch¶
Before implementing a feature, please ask one of the maintainers to avoid any unnecessary or double work. Let other people know through the relevant GitHub issue that you are planning on implementing it. Also for new features, first create an issue that can be discussed.
After implementing (with tests and documentation) create a PR on Github and let your changes be reviewed.
Virtual Environment¶
Create a virtual environment by double-clicking script/create_venv.py or by running the following command.
This will install all development, test and docs dependencies from pyproject.toml, install
DFetch as editable package
and install all runtime dependencies from pyproject.toml.
script/create_venv.py
Important
dfetch is primarily developed with python 3.13
Running in Github Codespaces¶
Github codespaces make it possible to edit dfetch directly in the browser in a VSCode instance. All dependencies are pre-installed and makes it easy to get started.
Tip
You can preview the documentation locally by running the Serve Docs task.
Codespaces will automatically suggest to open the forwarded port to view the
changes in your browser.
Running in VSCode¶
To debug or run directly from VSCode create the Virtual Environment.
Select the python from the virtual environment.
And open the dfetch.code-workspace.
Quality¶
To avoid any discussion about formatting black is used as code formatter. Next to that isort is used for sorting the imports. And doc8 is used as rst linter.
import-linter is used to guard the Architecture by verifying that imports between modules respect the C4 layer boundaries. Run it with:
lint-imports
Run script/check_quality.bat (or GitHub will run it for you). Alternatively when using VSCode run the Check Quality task from the command palette.
Testing¶
Unit tests¶
pytest is used as testing framework. All code contributed should be accompanied with unit tests.
Tests can be found in the tests folder.
To see coverage, in the virtual environment run pytest with coverage
pytest --cov=dfetch tests
From VSCode all tests can be run from the Test view.
Feature tests¶
Feature tests are used for higher-level integration testing of functionality.
For this behave is used as testing framework.
Feature files in the features folder contain plain-language examples that
demonstrate dfetch’s behaviour. The sentences in the feature files map to step
definitions in the features/steps folder.
Tests can be run directly from the command-line:
behave features
Feature files are tagged with the command they exercise (e.g. @update,
@check). You can run just the examples for a specific command using its tag:
behave features --tags=update
Alternatively in VSCode run the Run all feature tests task from the command palette.
To debug these tests, mark the Feature: or Scenario: to debug with the @wip tag
and run the Feature tests (wip) debug configuration in VSCode.
Creating documentation¶
Run script/create_docs.bat and open index.html in doc/_build/html to read it.
See This example for documenting the code.
Alternatively in VSCode run the Create Docs task from the command palette.
Design Guide¶
The docs and landing page share a single design system. Follow these tokens whenever you add new pages, diagrams, or HTML blocks to keep the visual language consistent.
Colour palette¶
Typography¶
Use for: inline code, CLI examples, hex values, token names, cheatsheet syntax, diagram labels where monospace is needed.
CSS tokens reference¶
Use CSS custom properties rather than raw hex values so changes propagate everywhere automatically.
Token |
Value |
Use for |
|---|---|---|
|
|
Primary action colour |
|
|
Hover / pressed state |
|
|
Secondary / info colour |
|
|
Hover on accent elements |
|
|
Body text, headings |
|
|
Secondary text |
|
|
Captions, labels, placeholders |
|
|
Warm section backgrounds |
|
|
Cool section backgrounds |
|
|
Card borders, dividers |
|
12px / 8px / 20px |
Border radius (card / badge / hero) |
|
— |
Box shadow tiers |
PlantUML diagrams¶
All flow and mindmap diagrams must use the shared skinparam block from
doc/static/uml/check.puml as a template. Key values:
Element |
Value |
Notes |
|---|---|---|
Activity background |
|
White nodes on transparent canvas |
Activity border |
|
1.5 pt thickness |
Diamond background |
|
Decision nodes use the cool tint |
Diamond border |
|
Consistent with accent colour |
Arrow colour |
|
Keeps arrows from competing with nodes |
Start node |
|
Filled amber disc |
Partition background |
|
Warm cream section bands |
Default font |
Arial, 12 pt, |
Matches |
Diataxis section colours¶
Each of the four Diataxis sections has its own accent colour. These are
applied automatically by doc/static/js/diataxis.js: it adds a CSS class
to <body> and to the sidebar caption elements so both the top page strip
and the sidebar navigation header reflect the section.
To add a new page to a section, add its filename (without .rst) to the
PAGE_SECTIONS map in doc/static/js/diataxis.js.
Releasing¶
Bump version number in
dfetch/__init__.py.Run
./script/release.py.Double check any feature scenarios for a version number.
Run all unit / feature tests.
Re-generate asciicasts using VSCode task (linux/mac).
Commit all release changes.
Create pull request & merge to
main.Create annotated tag on
mainand push it:
git checkout main
git pull
git tag -a '0.13.0' -m "Release version 0.13.0"
git push --tags
The
ci.ymljob will automatically create a draft release in GitHub Releases with all artifacts.Once the release is published, a new package is automatically pushed to PyPi.
After release, add new header to
CHANGELOG.rst:
Release 0.14.0 (unreleased)
====================================
