- JIRA to and Github Issue to track logical issues, including bugs, tasks and improvements.
- Mailing Lists for proposing, planning, discussing changes
- Confluence for documentation
- Github pull requests to manage the reviews and merge of specific code changes
That is, Mailing Lists are used for discussion and proposals, JIRA(or Github issue) and Confluence are used to describe what should be fixed or changed and high-level approaches, and Pull Requests and Review Board describe how to implement the change in code.
A mirror of the repository is hosted on GitHub.
By Helping Other Users
Helping answer user questions on the user@email@example.com mailing list is the first way to contribute to DistributedLog. There are always many new DistributedLog users; taking a few minutes to help answer a question is very valuable community service.
DistributedLog's release process is community-oriented, and members of the community can vote on new releases on the dev@firstname.lastname@example.org mailing list. DistributedLog users are encouraged to subscribe to this list to receive announcements (e.g the DistributedLog 0.4.0 release vote), and test their workloads on the newer release and provide feedback on any performance or correctness issues found in the newer release.
To modify the built-in documentation, checkout the instructions on How to build website and documentation.
- Is it clear that code must change? Proposing a JIRA(or Github issue) and pull request is appropriate only when a clear problem or change has been identified. If simply having trouble using DistributedLog, use the mailing list first, rather than considering filing a JIRA(or Github issue) or proposing a change. When in doubt, email email@example.com firstname.lastname@example.org first about the possible change.
- Search user@email@example.com and dev@firstname.lastname@example.org mailing list archives for related discussions. Often, the problem has been discussed before, with a resolution that doesn't require a code change, or recording what kind of changes will not be accepted as a resolution.
- Search Search JIRA for existing issues: https://issues.apache.org/jira/browse/DL
Type "DistributedLog / Github issue for existing issues.
For JIRA, type "DistributedLog [search terms]" at the top right search box; while for Github issue, type "search terms" in the "Filters" search box.
If a logically similar issue already exists, then contribute to the discussion on the existing JIRA/Github issue and pull request first, instead of creating a new one.
- Is the scope of the change matched to the contributor's level of experience? Anyone is qualified to suggest a typo fix, but refactoring recovery logic requires much more understanding of DistributedLog. Some changes require building up experience first (see above).
When contributing code, you affirm that the contribution is your original work and that you license the work to the project under the project's open source license. Whether or not you state this explicitly, by submitting any copyrighted material via pull request, email, review board or other means you agree to license the material under the project's open source license and warrant that you have the legal authority to do so.
Open JIRA ticket / Github issue
- Find the existing existing DistributedLog JIRA ticket that and Github issue that the change pertains to.
- Do not create a new JIRA ticket / Github issue, if creating a change to address an existing ticket in JIRA; add to the existing discussion and work instead.
- To avoid conflicts, assign the JIRA ticket to yourself(or comments on the github issue) if you plan to work on it.
- Look for existing pull requests or review boards that are linked from the the JIRA ticket(or github issue), to understand if someone is already working on it.
- If the change is new, then it usually needs a new JIRA ticket / Github issue. However, trivial changes, where "what should change" is virtually the same as "how it should change" do not require a JIRA ticket. Example: "Fix typos in Foo javadoc"
- If required, create a new JIRA ticket or Github issue:
- Provide a descriptive Title. "Update web UI" or "Problem in AsyncLogReader" is not sufficient. "Potential resource leak with unclosed AsyncLogReader" is good.
- Write a detailed description. For bug reports, this should ideally include a short reproduction of the problem. For new features, it may include a design document or a link to mailing list discussion.
- Set required fields:
- Issue Type. Generally, Bug, Improvement, New Feature, Documentation are the only types used in DistributedLogDistributedlog.
- Priority. Set to Major or below; higher priorities are generally reserved for committers to set. JIRA tends to unfortunately conflate "size" and "importance" in its Priority field values. Their meaning is roughly:
Blocker: pointless to release without this change as the release would be unusable to a large minority of users
Critical: a large minority of users are missing important functionality without this, and/or a workaround is difficult
Major: a small minority of users are missing important functionality without this, and there is a workaround
Minor: a niche use case is missing some support, but it does not affect usage or is easily worked around
Trivial: a nice-to-have change but unlikely to be any problem in practice otherwise
- Affects Version. For Bugs, assign at least one version that is known to exhibit the problem or need the change.
- To avoid conflicts, assign the JIRA ticket to yourself(or comments on the github issue) if you plan to work on it. Leave it unassigned otherwise.
- If If the change is a large change, consider inviting discussion on the issue at email@example.com firstname.lastname@example.org first before proceeding to implement the change.
- Fork the Github repository at https://github.com/apache/incubator-distributedlog if you haven't already.
- Clone your fork, create a new branch, push commits to the branch (review the , if you haven't already).
- Consider whether documentation or tests need to be added or updated as part of the change, and add them as needed.
- should be submitted along with code change.
- New server configuration settings should be added and documented in configuration file templates, and also documented in Documentation.
- Run all tests with "mvn clean apache-rat:check package findbugs:check" to verify that the code compiles, passes tests and passes findbugs checks.
- Open a pull request against the master branch of https://github.com/apache/incubator-distributedlog. (Only in special cases would the PR be opened against other branches.)
- The PR title should be of the form form DL-XXXX: Title , where DLor ISSUE-XXXX is : Title, where XXXX is the relevant JIRA and number or Github issue number, and Title may be the JIRA(or Github issue)'s title or a more specific title describing the PR itself.
- If the pull request is still a work in progress, and so is not ready to be merged, but needs to be pushed to Github to facilitate review, then add [WIP] after the JIRA(or Github issue)' id.
- Consider identifying committers or other contributors who have worked on the code being changed. Find the file(s) in GitHub and click "Blame" to see a line-by-line annotation of who changed the code last. You could add @username in the PR description to ping them immediately.
- Please state that the contribution is your original work and that you license the work to the project under the project's open source license.
- A comment with information about the pull request will be added to the JIRA ticket.
- Change the status of the JIRA to "Patch Available" if it is ready for review.
- The GitHub CI hook will test your changes.
- Once ready, the PR `checks` box will be updated with the test results along with a link to the full results on Jenkins.
- Investigate and fix failures caused by the pull request.
- Fixes can simply be pushed to the same branch from which you opened your pull request.
- Jenkins will automatically re-test when new commits are pushed, if an existing commit is amended, if the branch is rebased or if the pull request is closed or reopened.
- Despite our efforts, DistributedLog may have flaky tests at any given point, which may cause a build to fail. Unfortunately, it's not currently possible to restart the build by issuing a command. A workaround, as stated above, is to close and reopen the PR. If the failure is unrelated to your pull request and you have been able to run the tests locally successfully, please mention it in the pull request.
- Fixes can simply be pushed to the same branch from which you opened your pull request.
- Other reviewers, including committers, may comment on the changes and suggest modifications. Changes can be added by simply pushing more commits to the same branch.
- Lively, polite, rapid technical debate is encouraged from everyone in the community. The outcome may be a rejection of the entire change.
- Reviewers can indicate that a change looks suitable for merging with a comment such as: "I think the patch looks good. +1". DistributedLog uses DistributedLog uses "+1, -1" convention for indicating accepting or rejecting pull request, and also the pr merge script will use '+1' for pulling the reviewers' information..
- Sometimes, other changes will be merged which conflict with your pull request's changes. The PR can't be merged until the conflict is resolved. This can be resolved with "git fetch origin" followed by "git merge origin/master" and resolving the conflicts by hand, then pushing the result to your branch.
- Try to be responsive to the discussion rather than let days pass between replies.
Closing Your Pull Request / JIRA(or Github issue)
- If a change is accepted, it will be merged and the pull request will automatically be closed, along with the associated JIRA(or Github issue) if any
Note that in the rare case you are asked to open a pull request against a branch besides master, that you will actually have to close the pull request manually
The JIRA(or Github issue) will be Assigned to the primary contributor to the change as a way of giving credit. If the JIRA isn(or Github issue) isn't closed and/or Assigned promptly, comment on the JIRA(or Github issue).
If your pull request is ultimately rejected, please close it promptly
... because committers can't close PRs directly
Pull requests will be automatically closed by an automated process at Apache after about a week if a committer has made a comment like "mind closing this PR?" This means that the committer is specifically requesting that it be closed.
If a pull request has gotten little or no attention, consider improving the description or the change itself and ping likely reviewers again after a few days. Consider proposing a change that's easier to include, like a smaller and/or less invasive change.
If it has been reviewed but not taken up after weeks, after soliciting review from the most relevant reviewers, or, has met with neutral reactions, the outcome may be considered a "soft no". It is helpful to withdraw and close the PR in this case.
If a pull request is closed because it is deemed not the right approach to resolve a JIRA(or close a Github issue), then leave the JIRA(or Github issue) open. However if the review makes it clear that the issue identified in the JIRA is (or Github issue) is not going to be resolved by any pull request (not a problem, won't fix) then also resolve the JIRA(or close the Github issue).