Contribution Guidelines
status: valid
security: NO
safety: QM
version: 1
realizes: wp__sw_development_plan
doc__contribution_guidelines
Generic Document

Contribution Guidelines#

Scope and Size of a Pull Request#

A pull request does one thing and can be reviewed in one sitting. Content changes stay small; purely formal changes applied to many elements may be large. Every change carries a reason.

  1. One concern per pull request. A pull request does one thing: one fix, one step of a feature, one refactoring, or one formal change. Unrelated changes go into separate pull requests, even if they touch the same file.

  2. Reviewable in one sitting. Keep content changes small enough that a reviewer can understand all of them at once. As orientation, aim for about 400 changed lines of hand-written content or less. Larger content needs a reason in the description. New topics start with an issue (Issue Guideline (doc__issue_guideline)) or, for new features and enhancements, a Feature & Enhancement Proposal (Feature Request Guideline (doc__feature_request_guideline)).

  3. Formal changes may be large. A change that applies one rule to many elements (renaming an attribute across all needs, updating headers, migrating links, tool-generated formatting) may touch many files, if:

    • it is purely mechanical and contains no content change;

    • the description states the rule, and the command or script, so reviewers check the rule, not every line;

    • it is a pull request of its own, never mixed with content changes.

  4. Substance, not volume. Every change needs a reason that the description states. Rewording, reformatting or extending text without a content reason is not a contribution. Reviewers may close such pull requests without a detailed review.

  5. Split, do not stack up. Large work is delivered as a sequence of small pull requests: preparatory refactoring first, then the change itself. A draft pull request or an issue can show the whole picture.

  6. AI-assisted contributions follow wp__policies, which makes the Eclipse Generative AI Usage Guidelines applicable: the contributor has reviewed and understands every line and can defend it in review, and AI use should be disclosed (Assisted-by: trailer). The same size and substance rules apply.

  7. Reviewers may ask to split. A committer may request that a pull request is split before reviewing it, and should say along which line.

Note

Nothing here changes the Eclipse rule that contributions over 1,000 LoC need an IP Team review; rule 3 does not exempt a formal change from it.