Skip to content

Add draft PR guidelines to CONTRIBUTING.md #260

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

Open
laeubi wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add draft PR guidelines to CONTRIBUTING.md #260

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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: 30 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,36 @@ When you have set up your fork of a repository that you want to contribute to an
- After the PR is merged, the source branch used for the PR (in the fork) can be deleted.
- Your fork is now _out-of-date_ with the main (upstream) project repository. In case the "origin" remote of your local clone is the forked repository, you should get it back up to date. You can either use the _Sync Fork_ function on GitHub to update the fork and pull the `master` branch to your local clone, or pull the latest changes from "upstream" (the main project repository) into your local repository.

### Using Draft Pull Requests

GitHub allows you to mark a pull request as a [draft](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests) to indicate that it is not yet ready for final review or merging. Draft PRs are a valuable tool for collaboration, but they come with certain expectations in the Eclipse Platform community.
Copy link
Contributor

@merks merks Jan 12, 2026

Choose a reason for hiding this comment

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

Please start new sentence on new lines. Applies to all things below as well. For a bullets use

- This is is a bullet.
  This the second sentence in the same bullet.


#### What Draft Status Means

A draft PR indicates that:
Copy link
Contributor

@HeikoKlare HeikoKlare Jan 12, 2026

Choose a reason for hiding this comment

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

It might be helpful to add a sentence that the PR creator should add information in the PR description on what kind of feedback is desired on that specific PR in the current state. Otherwise this description could lead to the assumption that one can expect early feedback for a draft PR, but usually most people will probably ignore draft PRs until they are marked as ready for review.

- The changes are **not yet ready for submission/merging** (e.g., work is still in progress, tests are incomplete, or functionality is not fully working).
- You are **seeking early feedback** from the community on your approach, design decisions, or implementation.
- You may need **help or guidance** to resolve specific issues or to complete the work.
- You want to **share your progress** with others who might be interested or affected by the changes.

#### What Draft Status Does NOT Mean

A draft PR is **not**:
- A place to dump incomplete or unclear changes without context. Every PR, including drafts, should have a clear purpose and description.
- A shield against comments or reviews. Marking a PR as draft does not mean "leave me alone" – it means you welcome early feedback and collaboration.
- A substitute for local development or working in a private branch. If you're not ready to share your work or discuss it with others, keep it in your local repository or in a branch of your fork without creating a PR.

#### Requirements for Draft PRs

Even when marked as a draft, your PR should meet these basic requirements:

- **Clear intent and description**: Explain what you are trying to achieve, why the changes are being made, and what the current state is.
- **Understandable changes**: Others should be able to understand what you have done so far and what remains to be done. Consider using a task list in the description to track progress.
- **Specific questions or requests**: If you need help or feedback on particular aspects, clearly state what you need (_e.g._, "I'm unsure about the approach in XYZ.java" or "Tests for feature X are still missing").
Copy link
Contributor

@merks merks Jan 12, 2026

Choose a reason for hiding this comment

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

No need for italics e.g.

- **Reasonable completeness**: While not everything needs to be finished, the PR should represent a coherent chunk of work that others can review and comment on meaningfully.

When your draft PR is ready for final review, convert it to a regular PR using the "Ready for review" button. At that point, it should meet all the criteria from the [What does a valid PR look like?](#what-does-a-valid-pr-look-like-checklist) checklist above.

## Commit Message Recommendations

```
Expand Down