Skip to content

Latest commit

 

History

History
89 lines (60 loc) · 5.7 KB

contribute.adoc

File metadata and controls

89 lines (60 loc) · 5.7 KB
Raw
layout priority desc change_frequency
default
0.5
Contribute to CDI guide, Jakarta Specification Project.
weekly

Guidelines for contributing to CDI via the Jakarta Specification Project

Specification Project Membership

We develop CDI using an open mailing list. You don’t have to be an official member of the specification project to be part of the CDI community. We take into account all input from any member of the list

You should note that by using any of the communication mechanisms associated with CDI (including the mailing list, the GitHub issue tracker and the github repository) you agree that:

Resources

In addition to the mailing lists, we use GitHub to track issues https://github.com/eclipse-ee4j/cdi/issues. If you want to register an error in the specification (use the label spec-bug), request a clarification (use the label spec-clarification) or request a new feature (use the label spec-feature), please create an issue.

The CDI specification project lead (Antoine Sabot-Durand) will check the issue, and either request clarification if the report is not clear, or raise it with the specification project to discuss whether it should be fixed for 4.0.

The current draft of the specification is available on github at https://github.com/eclipse-ee4j/cdi/tree/master/spec - you are welcome to clone this repository, and create patches and submit pull requests if you wish. It is the duty of the specification project to ensure that the specification is consistent and well written, so expect some backwards and forwards before your patch is accepted!

Having crafted your changes, please push them to your fork on github, and then create a pull request. This creates an easy forum in which the specification project can review your changes.

Guidelines for interacting with the specification project

We hope the specification project can be a friendly and informal place to work, and as such we have laid out a few guidelines which it will help if you follow.

.

Consider whether you want to send an email, or add a comment in GitHub. If you wish to discuss the merits of a change or request more explanation of a proposed change, then send an email. If you want to make a technical proposal or propose an API design, add a comment to an issue. There are no hard and fast rules about when to send an email vs add a comment, but remember that comments are there for posterity, and can help people understand why certain design decision was made.

.

Try to make every post or comment say something meaningful. Endless "I agree" or "+1" emails aren’t that useful and distract from the real discussion about API improvements. Of course, if you strongly disagree with a proposal, please speak up, but in general silence is taken as approval! IRC is probably a better place if you want an informal exchange.

.

Please try keep the specification project a pleasant place - there is no need for rants, swearing or personal comments - these cannot help the specification in anyway. If you want to make an argument, back it up with concrete statements and examples.

We try to reach a consensus decision on all issues. If we can’t reach a consensus, we use polls to see what the wider community thinks. For issues on which a consensus still cannot be reached, and require a vote, we take a vote on the development list using the specification project committers as the voting group. Votes are rare, for example during CDI 1.1, we only had to vote on one issue.

Issue Resolution Rules

For minor issues where there is obvious fix and no one from the EG has commented, a pull request will be created and once reviewed by the project lead, merged into master.

For minor issues where there is discussion about how to fix, and for all major issues, a pull requests created when it appears that a consensus has been reached in the specification project. Normally, the pull request will not be merged for at least 2 weeks, giving the specification project time to review. If issues are raised by the specification project committers then these will be addressed and the 2 week period restarted.

If the specification project committers cannot reach consensus, then a simple majority will decide the outcome (as determined by a vote on the dev list). A similar 2 week period applies.

Close to submission deadlines, the 2 week period may be truncated.

Community Sponsored Issues

There are a number of issues which have merit (i.e. are addressing a valid problem/use case for CDI) but which have not been identified as a priority by the specification project. If an specification project committer wishes to see this issue resolved in the spec, then they can sponsor the issue. Practically this means that the sponsor:

  • is responsible for the spec changes (with help/review from specification project lead)

  • is responsible for TCK tests (help from TCK lead, review from specification project lead)

  • is not responsible for implementing the feature in a compatible implementation