hbase-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Sean Busbey (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (HBASE-4593) Design and document the official procedure for posting patches, commits, commit messages, etc. to smooth process and make integration with tools easier
Date Fri, 08 Aug 2014 05:26:14 GMT

    [ 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>&lt;jira-id&gt; &lt;jira-title&gt; (&lt;contributor-name-if-not-commit-author&gt;)</screen>
+                    <screen>HBASE-12345 Fix All The Things (jane@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)

Mime
View raw message