[
https://issues.apache.org/jira/browse/HBASE-4593?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14090324#comment-14090324
]
Sean Busbey commented on HBASE-4593:
------------------------------------
{quote}
+ <section xml:id="jira">
+ <title>Jira</title>
+ <para>Check for existing issues in <link
+
xlink:href="https://issues.apache.org/jira/browse/HBASE";>Jira</link>. If it's
+ either a new feature request, enhancement, or a bug, file a
ticket. </para>
+ <para>To check for existing issues which you can tackle as a
beginner, search for <link
+
xlink:href="https://issues.apache.org/jira/issues/?jql=project%20%3D%20HBASE%20AND%20labels%20in%20(beginner)"
+ >issues in JIRA tagged with the label 'beginner'</link>.
See <xref
+ linkend="getting.involved"/> for more information.</para>
{quote}
Now that this is 18.1.3, referring back to 18.1 doesn't make much sense.
{quote}
<section xml:id="maven.build.commands">
<title>Maven Build Commands</title>
@@ -1061,18 +1317,18 @@ batch.restart.rs.ratio=0.4f
</para>
<para>Note: use Maven 3 (Maven 2 may work but we suggest you use Maven
3).
</para>
- <section xml:id="maven.build.commands.compile">
+ <example xml:id="maven.build.commands.compile">
<title>Compile</title>
<programlisting language="bourne">
mvn compile
</programlisting>
- </section>
+ </example>
- <section xml:id="maven.build.commands.unitall">
+ <formalpara xml:id="maven.build.commands.unitall">
<title>Running all or individual Unit Tests</title>
<para>See the <xref linkend="hbase.unittests.cmds" /> section
above in <xref linkend="hbase.unittests" /></para>
- </section>
+ </formalpara>
<section xml:id="maven.build.hadoop">
<title>Building against various hadoop versions.</title>
{quote}
With the current layout, it looks like 18.10.1 can be moved under 18.4. With it
there, the intro to 18.10 can be dropped. Also the reference to 18.10 that's in
18.4.1 (esp since there is more info about different maven commands in 18.4
than 18.10).
{quote}
+ <para>If you need to revise your patch, leave the previous
patch file(s)
+ attached to the JIRA, and upload the new one, as in
<xref
+ linkend="submitting.patches.naming"/>. Cancel the
Patch Available flag
+ and then re-trigger it, by toggling the
<guibutton>Patch
+ Available</guibutton> button in JIRA. JIRA sorts
attached files by the
+ time they were attached, and has no problem with
multiple attachments with
+ the same name.</para>
+ </listitem>
+ <listitem>
+ <para>If you need to submit yuor patch against multiple
branches, rather than
+ just master, name each version of the patch with the
branch it is for, as in
+ <xref linkend="submitting.patches.naming"/>.</para>
{quote}
the links to "submitting.patches.naming" show up as ???. Are list items
reference-able or is this a rendering problem?
{quote}
+ <example xml:id="common.patch.feedback.space.invaders">
<title>Space Invaders</title>
- <para>Rather than do this...
+ <para>Do not use extra spaces around brackets. Use the second
style, rather than the
+ first.</para>
{quote}
Why do these start as examples and then turn into sections? For example, the
example on autogenerated code is similar in scope and presentation as the
section for useless javadocs.
We should make them all one or the other. I'd favor sections, but we're already
deeply nested.
{quote}
+ <section xml:id="common.patch.feedback.writable">
+ <title>Implementing Writable</title>
+ <note>
+ <title>Applies pre-0.96 only</title>
+ <para>In 0.96, HBase moved to protocol buffers
(protobufs). The below section on
+ Writables applies to 0.94.x and previous, not to 0.96
and beyond. </para>
+ </note>
+ <para>Every class returned by RegionServers must implement the
<code>Writable</code>
+ interface. If you are creating a new class that needs to
implement this
+ interface, do not forget the default constructor. </para>
+ </section>
{quote}
Since this example is only for some branches, it should probably go after all
the other guidelines.
{quote}
+ <guilabel>Review Group</guilabel>. If you fill in
the
+ <guilabel>Bugs</guilabel> field, the review board
is attached to the
+ relevant JIRA automatically. The more fields you fill
in, the better. Click
{quote}
I don't think this is true. At the very least I've been having to attach them
manually (see HBASE-11658). Filling in the bugs field will automatically
provide a link from the reviewboard to the jira, but not the reverse.
{quote}
+ <screen><jira-id> <jira-title>
(<contributor-name-if-not-commit-author>)</screen>
+ <screen>HBASE-12345 Fix All The Things
(j...@example.com)</screen>
+ <para>If the submitter used <command>git
format-patch</command> to generate the
+ patch, their commit message is in their patch and you
can use that.</para>
{quote}
Refer to contributor instead of submitter.
A warning about checking that the contributor properly started their message
with a jira-id would be good.
> Design and document the official procedure for posting patches, commits,
> commit messages, etc. to smooth process and make integration with tools easier
> -------------------------------------------------------------------------------------------------------------------------------------------------------
>
> Key: HBASE-4593
> URL: https://issues.apache.org/jira/browse/HBASE-4593
> Project: HBase
> Issue Type: Task
> Components: documentation
> Reporter: Jonathan Gray
> Assignee: Misty Stanley-Jones
> Attachments: Chapter_18_and_19.pdf, HBASE-4593.patch, HBASE-4593.patch
>
>
> I have been building a tool (currently called reposync) to help me keep the
> internal FB hbase-92-based branch up-to-date with the public branches.
> Various inconsistencies in our process has made it difficult to automate a
> lot of this stuff.
> I'd like to work with everyone to come up with the official best practices
> and stick to it.
> I welcome all suggestions. Among some of the things I'd like to nail down:
> - Commit message format
> - Best practice and commit message format for multiple commits
> - Multiple commits per jira vs. jira per commit, what are the exceptions and
> when
> - Affects vs. Fix versions
> - Potential usage of [tags] in commit messages for things like book, scripts,
> shell... maybe even whatever is in the components field?
> - Increased usage of JIRA tags or labels to mark exactly which repos a JIRA
> has been committed to (potentially even internal repos? ways for a tool to
> keep track in JIRA?)
> We also need to be more strict about some things if we want to follow Apache
> guidelines. For example, all final versions of a patch must be attached to
> JIRA so that the author properly assigns it to Apache.
--
This message was sent by Atlassian JIRA
(v6.2#6252)
