Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Contributing info update #262

Merged
merged 2 commits into from
Feb 27, 2023
Merged

Contributing info update #262

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
38924e8
Fix typos
mih Feb 27, 2023
d076ff4
Write-up on patching
mih Feb 27, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 24 additions & 6 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ If in doubt, it is advisable to file an issue and ask for feedback before prepar

New feature releases of `datalad-next` are happening more frequently. Typically, every 4-6 weeks.

New features depending on other `datalad-next` features are, quite obviously, better directed at `datalad-next`.
New features depending on other `datalad-next` features are, by necessity, better directed at `datalad-next`.

## What is important for a successful contribution to `datalad-next`?

Expand All @@ -36,14 +36,32 @@ In `datalad-next`, all code is organized in shallow sub-packages. Each sub-packa

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.

There is no limit on the number of files. Contributors should strive for files with less than 500 lines of code.
There is no limit to the number of files. Contributors should strive for files with less than 500 lines of code.

Within a sub-package, code should generally use relative imports. The corresponding tests should also import the tested code via relative imports.

Code users should be able to import the most relevant functionality from the subpackage's `__init__.py`.
Code users should be able to import the most relevant functionality from the sub-package's `__init__.py`.

If possible, sub-packages should have a "central" place for imports of functionality from outside `datalad-next` 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.
If possible, sub-packages should have a "central" place for imports of functionality from outside `datalad-next` 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`.

Sub-packages should be as self-contained as possible. Individual components in `datalad-next` should strive to be easily migratable into the DataLad core package. This means that organization principles like "all exceptions go into a single location" do not apply. For example, each sub-package should define it exceptions separately from others. When functionality is shared between sub-packages, absolute imports should be made.
Sub-packages should be as self-contained as possible. Individual components in `datalad-next` should strive to be easily migratable to the DataLad core package. This means that any organization principles like *all-exceptions-go-into-a-single-location-in-datalad-next* do not apply. For example, each sub-package should define its exceptions separately from others. When functionality is shared between sub-packages, absolute imports should be made.

There is one special sub-package in `datalad-next`: `patches`. All runtime patches to be applies to the DataLad core package must be places here.
There is one special sub-package in `datalad-next`: `patches`. All runtime patches to be applied to the DataLad core package must be placed here.

## Runtime patches

The `patches` sub-package contains all runtime patches that are applied by `datalad-next`. Patches are applied on-import of `datalad-next`, and may modify arbitrary aspects of the runtime environment. A patch is enabled by adding a corresponding `import` statement to `datalad_next/patches/__init__.py`. The order of imports in this file is significant. New patches should consider behavior changes caused by other patches, and should be considerate of changes imposed on other patches.

`datalad-next` is imported (and thereby its patches applied) whenever used
directly (e.g., when running commands provided by `datalad-next`, or by an
extension that uses `datalad-next`). In addition, it is imported by the
DataLad core package itself when the configuration item
`datalad.extensions.load=next` is set.

Patches modify an external implementation that is itself subject to change. To improve the validity and longevity of patches, it is helpful to consider a few guidelines:

- Patches should use `datalad_next.utils.apply_patch()` to perform the patching, in order to yield uniform (logging) behavior

- Patches should be as self-contained as possible. The aim is for patches to be merged upstream (at the patched entity) as quickly as possible. Self-contained patches facilitate this process.

- Patches should maximally limit their imports from sources that are not the patch target. The helps to detect when changes to the patch target (or its environment) are made, and also helps to isolate the patch from changes in the general environment of the patches software package that are unrelated to the specific patched code.