Date: Tue, 19 Mar 2024 10:00:24 +0000 (UTC)
Message-ID: <115955398.56183.1710842424139@cwiki-he-fi.apache.org>
Subject: Exported From Confluence
MIME-Version: 1.0
Content-Type: multipart/related;
boundary="----=_Part_56182_1196318028.1710842424139"
------=_Part_56182_1196318028.1710842424139
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
Content-Location: file:///C:/exported.html
This page documents the best way to make various types of contri=
bution to Apache DistributedLog, including what is required before submitti=
ng a code change.
There may be bugs or possible improvements to this page, so please help =
us improve it. Credit to the Spark project. We've borrow liberally from their doc=
umentation.
Contributing to DistributedLog doesn't just mean writing code. Helping n=
ew users on the mailing list, testing releases, and improving documentation=
are also welcome. In fact, proposing significant code change usually requi=
res first gaining experience and credibility within the community by helpin=
g in other ways. This is also a guide to becoming an effective contributor.=
Overview
DistributedLog uses:
- JIRA and Github I=
ssue to track logical issues, including bugs, tasks and improvemen=
ts.
- Mailing Lists for proposing, planning, discussing changes
- Developer: distributedlog-dev@boo=
kkeeper.apa=
che.org
- 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 Gi=
thub issue) and Confluence are used to describe what should be fixed or cha=
nged and high-level approaches, and Pull Requests and Review Board describe=
how to implement the change in code.
Code Source
A mirror of the repository is hosted on GitHub.<=
/p>
Contributions
By Helping Othe=
r Users
Helping answer user questions on the dis=
tributedlog-user@bookkeeper.apache.org mailing list is the first w=
ay to contribute to DistributedLog. There are always many new DistributedLo=
g users; taking a few minutes to help answer a question is very valuable co=
mmunity service.
Contributors should subscribe to this list and follow it in order to kee=
p up to date on what's happening in DistributedLog. Answering questions is =
an excellent and visible way to help the community, which also demonstrates=
your expertise.
By Testing Releas=
es
DistributedLog's release process is community-oriented, and members of t=
he community can vote on new releases on the distributedlog-dev@bookkeeper.apache.org mailing list. Distribute=
dLog users are encouraged to subscribe to this list to receive announcement=
s (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 is=
sues found in the newer release.
By Reviewing Cha=
nges
Changes to DistributedLog source code are proposed, reviewed and committ=
ed via Pull Request (described later). Anyone can view and comment on activ=
e changes here. Reviewing others' changes is a good way to learn how the ch=
ange process works and again exposure to activity in various parts of the c=
ode. You can help by reviewing the changes and asking questions or pointing=
out issues =E2=80=93 as simple as typos or small issues of style.
Documentation =
Changes
To have us add a link to an external tutorial you wrote, simply email to=
distributedlog-dev@bookkeeper.apache.org.
To modify the built-in documentation, checkout the instructions on =
How to build website and documentation=
a>.
Pr=
eparing to Contribute Code Changes
Before proceeding to code changes, contributors should evaluate if the p=
roposed change is likely to be relevant, new and actionable:
- 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 usi=
ng DistributedLog, use the mailing list first, rather than considering fili=
ng a JIRA(or Github issue) or proposing a change. When in doubt, email distriburedlog-user@bookkeeper.apache.org f=
irst about the possible change.
- Search distributedlog-user@bookkeeper.a=
pache.org and distributedlog-dev@bo=
okkeeper.apache.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 acc=
epted as a resolution.
- Search JIRA / 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 discuss=
ion on the existing JIRA/Github issue and pull request first, instead of cr=
eating a new one.
- Is the scope of the change matched to the contributor's level of experi=
ence? Anyone is qualified to suggest a typo fix, but refactoring recovery l=
ogic requires much more understanding of DistributedLog. Some changes requi=
re building up experience first (see above).
Code Review Crit=
eria
Before considering how to contribute code, it's useful to understand how=
code is reviewed, and why changes may be rejected. Simply put, changes tha=
t have many or large positives, and few negative effects or risks, are much=
more likely to be merged, and merged quickly. Risky and less valuable chan=
ges are very unlikely to be merged, and may be rejected outright rather tha=
n receive iterations of review.
Positives
- Fixes the root cause of a bug in existing functionality
- Adds functionality or fixes a problem needed by a large number of users=
- Simple, targeted
- Has tests
- Reduces complexity and lines of code
- Change has already been discussed and is known to committers
Negatives
- Adds complexity that only helps a niche use case
- Changes a public API or semantics (rarely allowed)
- Makes lots of modifications in one "big bang" change
- Band-aids a symptom of a bug only
Contributin=
g Code Changes
Please review the preceding section before proposing a code change. This=
section documents how to do so.
Open JIR=
A ticket / Github issue
- Find the existing DistributedLog JIRA ticket 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; add to the existing discussion and work instea=
d.
- To avoid conflicts, assign the JIRA ticket to yourself(or comments on t=
he github issue) if you plan to work on it.
- Look for existing pull requests or review boards that are linked from t=
he the JIRA ticket(or github issue), to understand if someone is already wo=
rking 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 th=
e same as "how it should change" do not require a JIRA ticket. Example: "Fi=
x typos in Foo javadoc"
- If required, create a new JIRA ticket or Github issue:
- Provide a descriptive Title. "Update web UI" or "Problem in AsyncLogRea=
der" is not sufficient. "Potential resource leak with unclosed AsyncLogRead=
er" is good.
- Write a detailed description. For bug reports, this should ideally incl=
ude 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 Distributedlog.
- 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 wit=
hout this change as the release would be unusable to a large minority of us=
ers
Critical: a large minority of use=
rs 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 missin=
g some support, but it does not affect usage or is easily worked around
Trivial: a nice-to-have change bu=
t unlikely to be any problem in practice otherwise
- Component
- Affects Version. Fo=
r 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.
- I=
f the change is a large change, consider inviting discussion on the issue a=
t distributedlog-dev@bookkeeper.apach=
e.org first before proceeding to implement the change.
Git Workflow
Pull Request
- 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 (revie=
w the DistributedLog Coding Guidelines , 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.
- Doc changes should be submitted =
along with code change.
- New server configuration settings should be added and documented in con=
figuration 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.<=
/li>
- Open a pull request against the mas=
ter branch of https://github.com/apache/i=
ncubator-distributedlog. (Only in special cases would the PR be opened =
against other branches.)
- The PR title should be of the form DL-XXXX: Title or ISSUE-XXXX: Title=
strong>, where XXXX is the relevant JIRA number or Githu=
b 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 o=
n the code being changed. Find the file(s) in GitHub and click "Blame" to s=
ee a line-by-line annotation of who changed the code last. You could add&nb=
sp;@username in the PR description to ping them immediately.
- Please state that the contribution is your original work and that you l=
icense 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 a=
long 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 you=
r pull request.
- Jenkins will automatically re-test when new commits are pushed, if an e=
xisting 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 p=
oint, which may cause a build to fail. Unfortunately, it's not currently po=
ssible to restart the build by issuing a command. A workaround, as stated a=
bove, is to close and reopen the PR. If the failure is unrelated to your pu=
ll request and you have been able to run the tests locally successfully, pl=
ease mention it in the pull request.
The Review Process=
- Other reviewers, including committers, may comment on the changes and s=
uggest modifications. Changes can be added by simply pushing more commits t=
o the same branch.
- Lively, polite, rapid technical debate is encouraged from everyone in t=
he 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 us=
es "+1, -1" convention for indicating accepting or rejecting pull request, =
and also the pr merge script will use '+1' for pulling the reviewers' infor=
mation..
- Sometimes, other changes will be merged which conflict with your pull r=
equest's changes. The PR can't be merged until the conflict is resolved. Th=
is can be resolved with "git fetch origin" followed by "git merge origin/ma=
ster" 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 betwee=
n replies.
Closing Your Pull Request / JIRA(or Github issue)
- If a change is accepted, it will be merged and the pull request will au=
tomatically be closed, along with the associated JIRA(or Github issue) if a=
ny
Note that in the rare case you ar=
e asked to open a pull request against a branch besides master, that you wi=
ll 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 credi=
t. If the JIRA(or Github issue) isn't closed and/or Assigned promptly,=
comment on the JIRA(or Github issue).
If your pull request is ultimatel=
y rejected, please close it promptly
... because committers can't clos=
e PRs directly
Pull requests will be automatical=
ly closed by an automated process at Apache after about a week if a committ=
er has made a comment like "mind closing this PR?" This means that the comm=
itter is specifically requesting that it be closed.
If a pull request has gotten litt=
le or no attention, consider improving the description or the change itself=
and ping likely reviewers again after a few days. Consider proposing a cha=
nge that's easier to include, like a smaller and/or less invasive change.=
span>
If it has been reviewed but not t=
aken up after weeks, after soliciting review from the most relevant reviewe=
rs, or, has met with neutral reactions, the outcome may be considered a "so=
ft 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 appro=
ach to resolve a JIRA(or close a Github =
issue), then leave the JIRA(or Github issue) open. However if the re=
view makes it clear that the issue identified in the JIRA(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).
------=_Part_56182_1196318028.1710842424139--