[OPEN-ILS-DEV] Documentation commits and sign-off procedure

[Dan Scott]

On Jul 6, 2012 9:20 AM, "Soulliere, Robert" <
robert.soulliere at mohawkcollege.ca> wrote:
>
> Hi,
>
> I was hoping to do a lot of documentation committing in the next month I
just wanted to check in about  commit sign-off procedure as it relates to
documentation under 3 scenarios:
>
> 1. An author sends me documentation in a format needing to be converted
to asciidoc. I convert it and commit it to the repository -- Would it be OK
for me to be the single sign-off on this commit using the commit option to
indicate that there is an original author and my sign off.
> e.g. git commit --author="Original Author <email at address.com>"

Sounds good to me; this way the author gets credited in gitstats and the
like.

> 2.  I make a few typo fixes or update the upgrade instructions to update
version  references -- Can these quick fixes be direct commits or do I need
an additional sign-offs?

I think the goal is to have commit processes that offer some value (like
who wrote or changed what and why, so that we have a meaningful commit
history and change log), not to force painful overhead. Also, the chance of
a typo fix breaking the doc build seems low, so I don't see a great
advantage to requiring a second sign-off in this case.

> 3. I author a new section or chapter or do a massive overhaul of a
section -- In this case, I would create working branch – make changes --
 cherry pick commit – add pull request in launchpad – wait for
review/sign-off – commit to main repo (or will someone else do the final
commit?).
> How many sign-offs should be required for documentation commits? Also, is
there a time frame for waiting for sign-offs before I can just commit it
without additional sign-off?

I don't know if you need a second sign-off in this case, either. Given how
few DIG committers there are, we wouldn't want to impede the progress of
the docs just to keep a perfectly parallel commit process with the code.

> Also if someone adds documentation from a different working branch and
asks me to pull into the main repo, could I just do the cherry pick and
commit to the main repo as a single sign-off, or do I follow a longer
review process and go through launchpad?

I would cherry-pick and commit.

> My main goals is for documentation to be updated in a timely manner but
to also follow the proper procedure for commits. I am concerned that we
will have fewer sign-off persons to test and sign off on documentation
changes compared to code commits.

Agreed!
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://libmail.georgialibraries.org/pipermail/open-ils-dev/attachments/20120707/ff1e2929/attachment.htm>