|
| 1 | +# Contributing to `datalad-core` |
| 2 | + |
| 3 | +- [What contributions are most suitable for `datalad-core`](#when-should-i-consider-a-contribution-to-datalad-core) |
| 4 | +- [Style guide](#contribution-style-guide) |
| 5 | +- [Code organization](#code-organization) |
| 6 | +- [Test output](#test-output) |
| 7 | +- [CI workflows](#ci-workflows) |
| 8 | + |
| 9 | + |
| 10 | +## When should I consider a contribution to `datalad-core`? |
| 11 | + |
| 12 | +This package aims to be a lightweight library, to be used by any and all DataLad packages. |
| 13 | +Contributed code should match this scope. |
| 14 | +Special-interested functionality or code concerned with individual services and packages should be contributed elsewhere. |
| 15 | +Morever, additional software dependencies should not be added carelessly -- a reasonably small dependency footprint is a key goal of this library. |
| 16 | + |
| 17 | + |
| 18 | +## Contribution style guide |
| 19 | + |
| 20 | +A contribution must be complete with code, tests, and documentation. |
| 21 | + |
| 22 | +`datalad-core` is a place for mature, and modular code. Therefore, tests are essential. A high test-coverage is desirable. Contributors should clarify why a contribution is not covered 100%. Tests must be dedicated for the code of a particular contribution. It is not sufficient, if other code happens to also exercise a new feature. |
| 23 | + |
| 24 | +New code should be type-annotated. At minimum, a type annotation of the main API (e.g., function signatures) is needed. A dedicated CI run is testing type annotations. |
| 25 | + |
| 26 | +Docstrings should be complete with information on parameters, return values, and exception behavior. Documentation should be added to and rendered with the sphinx-based documentation. |
| 27 | + |
| 28 | +### Conventional commits |
| 29 | + |
| 30 | +Commits and commit messages must be [Conventional Commits](https://www.conventionalcommits.org). Their compliance is checked for each pull request. The following commit types are recognized: |
| 31 | + |
| 32 | +- `feat`: introduces a new feature |
| 33 | +- `fix`: address a problem, fix a bug |
| 34 | +- `doc`: update the documentation |
| 35 | +- `rf`: refactor code with no change of functionality |
| 36 | +- `perf`: enhance performance of existing functionality |
| 37 | +- `test`: add/update/modify test implementations |
| 38 | +- `ci`: change CI setup |
| 39 | +- `style`: beautification |
| 40 | +- `chore`: results of routine tasks, such as changelog updates |
| 41 | +- `revert`: revert a previous change |
| 42 | +- `bump`: version update |
| 43 | + |
| 44 | +Any breaking change must have at least one line of the format |
| 45 | + |
| 46 | + BREAKING CHANGE: <summary of the breakage> |
| 47 | + |
| 48 | +in the body of the commit message that introduces the breakage. Breaking changes can be introduced in any type of commit. Any number of breaking changes can be described in a commit message (one per line). breaking changes trigger a major version update, and form a dedicated section in the changelog. |
| 49 | + |
| 50 | +### Pull-requests |
| 51 | + |
| 52 | +The projects uses pull requests (PR) for contributions. |
| 53 | +However, PRs are considered disposable, and no essential information must be uniquely available in PR descriptions and discussions. |
| 54 | +All important (meta-)information must be in commit messages. |
| 55 | +It is perfectly fine to post a PR with *no* additional description. |
| 56 | + |
| 57 | +### Code organization |
| 58 | + |
| 59 | +In `datalad-core`, all code is organized in shallow sub-packages. Each sub-package is located in a directory within the `datalad_core` package. |
| 60 | + |
| 61 | +Consequently, there are no top-level source files other than a few exceptions for technical reasons (`__init__.py`, `conftest.py`, `_version.py`). |
| 62 | + |
| 63 | +A sub-package contains any number of code files, and a `tests` directory with all test implementations for that particular sub-package, and only for that sub-package. Other, deeper directory hierarchies are not to be expected. |
| 64 | + |
| 65 | +There is no limit to the number of files. Contributors should strive for files with less than 500 lines of code. |
| 66 | + |
| 67 | +Within a sub-package, tests should import the tested code via relative imports. |
| 68 | + |
| 69 | +Code users should be able to import the most relevant functionality from the sub-package's `__init__.py`. Only items importable from the sub-package's top-level are considered to be part of its "public" API. If a sub-module is imported in the sub-package's `__init__.py`, consider adding `__all__` to the sub-module to restrict wildcard imports from the sub-module, and to document what is considered to be part of the "public" API. |
| 70 | + |
| 71 | +Sub-packages should be as self-contained as possible. When functionality is shared between sub-packages, absolute imports should be made. |
| 72 | + |
| 73 | + |
| 74 | +### Imports |
| 75 | + |
| 76 | +#### Import centralization per sub-package |
| 77 | + |
| 78 | +If possible, sub-packages should have a "central" place for imports of functionality from outside `datalad-core` and the Python standard library. Other sub-package code should then import from this place via relative imports. This aims to make external dependencies more obvious, and import-error handling and mitigation for missing dependencies simpler and cleaner. Such a location could be the sub-package's `__init__.py`, or possibly a dedicated `dependencies.py`. |
| 79 | + |
| 80 | +### Test output |
| 81 | + |
| 82 | +Tests should be silent on stdout/stderr as much as possible. |
| 83 | +In particular (but not only), result renderings of DataLad commands must no be produced, unless necessary for testing a particular feature. |
| 84 | + |
| 85 | + |
| 86 | +## CI workflows |
| 87 | + |
| 88 | +The addition of automation via CI workflows is welcome. |
| 89 | +However, such workflows should not force developers to depend on, or have to wait for any particular service to run a workflow before they can discover essential outcomes. |
| 90 | +When such workflows are added to online services, an equivalent setup for local execution should be added to the repository. |
| 91 | +The `hatch` environments and tailored commands offer a straightforward, and discoverable method to fulfill this requirement (`hatch env show`). |
0 commit comments