Skip to content

feat: add developer instructions - #183

Open
Oisin-M wants to merge 11 commits into
developfrom
feat/dev_instructions
Open

Oisin-M wants to merge 11 commits into
developfrom
feat/dev_instructions

Conversation

@Oisin-M

@Oisin-M Oisin-M commented Jul 30, 2026 •

Copy link
Copy Markdown
Contributor

Description

Time has come to add some centralised developer instructions to the main earthkit packages that each of the subpackages can link to. Idea is to have as much as possible in the central instructions and as little as possible subpackage-specific instructions so it's more seamless to contribute across the stack and additionally also hopefully even more seamless experience when using the different components.

In this PR, added:

  • documentation guidelines (diataxis)
  • contributing guidelines
  • guidelines for which package to put functionality in
  • guidelines for naming (long clear function names, short arguments etc.)
  • functional-first design (probably most debatable - needs discussion)
  • maximum interoperability with other Python libraries + earthkit packages
  • preference for one ground truth implementation over multiple
  • guidelines on dependencies (minimal for components, most functionality out of the box for toplevel)
  • missing value handling guidance

Contributor Declaration

By opening this pull request, I affirm the following:

  • All authors agree to the Contributor License Agreement.
  • The code follows the project's coding standards.
  • I have performed self-review and added comments where needed.
  • I have added or updated tests to verify that my changes are effective and functional.
  • I have run all existing tests and confirmed they pass.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@EddyCMWF EddyCMWF left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved from a technical implementation and general structure point of view.

@Oisin-M
Oisin-M requested a review from iainrussell July 31, 2026 13:58

Functions should:

* have explicit inputs and outputs i.e. avoid `**kwargs`

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps we should soften this - we do use kwargs quite a lot

@Oisin-M Oisin-M Nov 19, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* have explicit inputs and outputs i.e. avoid `**kwargs`
* have well-documented inputs and outputs e.g. avoid bare `**kwargs` where possible

@iainrussell iainrussell left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @Oisin-M,
I really like these docs. I pushed some small fixes, hope you are ok with them. Plus one comment on the kwargs which I think needs to be re-phrased.

Comment thread docs/development/contributing.rst Resolved
@Oisin-M

Oisin-M commented Nov 19, 2026

Copy link
Copy Markdown
Contributor Author

Hi @Oisin-M, I really like these docs. I pushed some small fixes, hope you are ok with them. Plus one comment on the kwargs which I think needs to be re-phrased.

Thanks for the fixes! I added a suggestion for the kwargs line - let me know if it aligns with what you had in mind

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants