New Workflow

[David A. Harding]

Hi,

Saļvann suggested that our new post-merge[1] workflow submit pull
requests directly to the Bitcoin.org repository for most things, with
another repository being used for some things. I was wondering if he
could explain the basic steps for each of the following four scenarios:

1. Fixes or substitutions for content already published. For example,
the Core devs lower the suggested minimum transaction fee, so we have
to update that part of the text.

2. Small additions of new content. For example, we want to add a
sentence or two about adding creation dates to HD wallet seeds
to make recovering transactions using an SPV wallet much quicker.

3. Large additions of new content. For example, we write a section about
hardware and service-based multisig wallets.

4. Global changes. For example, we decide (with approval) to change
block chain to blockchain.

I also wonder if Saļvann could address two concerns I have about
sending pull requests directly to Bitcoin.org:

* Should we be worried about overwhelming the over 50 people who watch
the main repository? In writing the docs, we've generated 130
issues/pulls on saivann/bitcoin.org in two months; the main
bitcoin/bitcoin.org repository has only had 396 issues/pulls in
three *years*.

* Should we be worried about slow merges creating inconsistent docs?
Pull requests to bitcoin/bitcoin.org will probably spend more time in
review than the pull requests we've submitted to saivann/bitcoin.org,
and this may leave us with a backlog of pull requests which, when
merged together, will produce a document none of us have actually
reviewed. Alternatively, it could mean coordinators such as Saļvann
have to do a lot of extra reviewing to keep things consistent.

Thanks,

-Dave

[1] The pull request seems to be going well. We haven't received a lot
of feedback, but if we had some fundamental problem, I expect it
would've been mentioned by now. It's been 48 hours since we received
our last "please fix"-type comment, so hopefully we won't have to
wait much longer until we merge.
--
David A. Harding

[Saïvann Carignan]

Le 2014-05-13 10:48, David A. Harding a écrit :
> Hi,
>
> Saļvann suggested that our new post-merge[1] workflow submit pull
> requests directly to the Bitcoin.org repository for most things, with
> another repository being used for some things. I was wondering if he
> could explain the basic steps for each of the following four scenarios:

Good idea! (Sorry in advance for the wall of text)

Here's what I had in mind, (although I think this should not be seen as
restrictive rules, but just general guidelines).

*General discussions*: They can take place on the mailing list. And
since an image is worth a thousand words, providing real examples (e.g.
screenshots, previews & branches) is encouraged.

*Decisions*: Changes that are likely to require a lot of discussion
could be discussed on the mailing list before opening a pull request,
and final decisions would be taken on pull requests. Reviewers would
either approve (LGTM) or suggest change and provide explanation of the
change (no opposition without explanation and suggestion). Pull requests
that are fundamentally questioned would not be merged until they get a
rouch consensus (but small disagreements like a choice of words
shouldn't block a pull req).

*Reviews*: Since each pull request is going to be unique, I think David
and I could just use good judgment to determine what kind of reviews
each change require. In any case, keeping the pull request open for a
few days and announcing one day before merging on GitHub and
#bitcoin-dev is a good practice. While some pull req could be merged in
the absence of feedback, some others might benefit from asking a few
questions or reviews on #bitcoin-dev or BitcoinTalk. Typo fixes
shouldn't require new reviews or pull request IMO.

*Large projects*: I think it makes sense to open a pull request on
bitcoin.org only once the suggested content is complete and minimally
tested. So it can be only one contributor writing a new section, or many
people working in group on a separate repository, and then submit a pull
request once the result is ready to be reviewed.

*Terminology*: I think we should try to stick to established
terminology, discuss changes on the mailing list and avoid making
changes without a good consensus. The documentation style guide could be
kept up to date on the bitcoin.org Wiki.

*README*: I am not fond of "too much rules and guidelines", I often find
it better to assist people from a real context, and have clear code with
comments they can easily understand. But as for providing some
references and help, we could add a concise "Documentation" subsection
in the README https://github.com/bitcoin/bitcoin.org#how-to-participate
Pointing to the Style Guide page and Mailing list.

> 1. Fixes or substitutions for content already published. For example,
> the Core devs lower the suggested minimum transaction fee, so we have
> to update that part of the text.

This example is a non-controversial change, so IMO a simple pull request
could be opened, and merged after a few days if there's no feedback.

> 2. Small additions of new content. For example, we want to add a
> sentence or two about adding creation dates to HD wallet seeds
> to make recovering transactions using an SPV wallet much quicker.

Depending on how the change is controversial and how confident we are
that the content is accurate, we could ask more feedback before merging,
or merge this a few day later, one day after announcing the pull req is
going to be merged on #bitcoin-dev / GitHub.

> 3. Large additions of new content. For example, we write a section about
> hardware and service-based multisig wallets.

I think someone can either provide an already ready-to-merge version
that will be discussed on the pull request. Or the project can be
announced to the mailing list and many contributors can work together on
a personal repository until everyone agrees it's good enough to be
submitted to bitcoin.org .

> 4. Global changes. For example, we decide (with approval) to change
> block chain to blockchain.

This one is a particular case I think, as it affects a status-quo that
goes beyond just bitcoin.org . So IMO ideally we would need some reddit
/ bitcointalk thread / voting pool with a good number of participants
along with Google stats, so if there's any decision made here, there
will be strong arguments behind it, it will be applied more globally
(not just on bitcoin.org) and it won't be reversed a year later.

> I also wonder if Saļvann could address two concerns I have about
> sending pull requests directly to Bitcoin.org:
>
> * Should we be worried about overwhelming the over 50 people who watch
> the main repository? In writing the docs, we've generated 130
> issues/pulls on saivann/bitcoin.org in two months; the main
> bitcoin/bitcoin.org repository has only had 396 issues/pulls in
> three *years*.

I think it would only be good to increase activity here. Although IMO
it's still good to keep some noise away (e.g. draft projects not ready
for final review, long discussions on the mailing list, etc).

> * Should we be worried about slow merges creating inconsistent docs?
> Pull requests to bitcoin/bitcoin.org will probably spend more time in
> review than the pull requests we've submitted to saivann/bitcoin.org,
> and this may leave us with a backlog of pull requests which, when
> merged together, will produce a document none of us have actually
> reviewed. Alternatively, it could mean coordinators such as Saļvann
> have to do a lot of extra reviewing to keep things consistent.

I think we can only expect slow merge for the first huge pull request.
To avoid this kind of problem for smaller future pull requests, I think
we should make good use of the mailing list, #bitcoin-dev, bitcointalk,
etc. and not be afraid to merge what we're reasonably confident with.
I've also suggested to David we could use a small "This documentation is
in Beta" disclaimer, which could let us move a little bit faster until
we have some experienced reviewers.

Saïvann

[David A. Harding]

On Tue, May 13, 2014 at 01:55:50PM -0400, Saïvann Carignan wrote:
>
> Le 2014-05-13 10:48, David A. Harding a écrit :
> > Hi,
> >
> > Saļvann suggested that our new post-merge[1] workflow submit pull
> > requests directly to the Bitcoin.org repository for most things, with
> > another repository being used for some things. I was wondering if he
> > could explain the basic steps for each of the following four scenarios:
>
> Good idea! (Sorry in advance for the wall of text)

I read the whole thing looking for something to comment on, but it all
sounds good to me. Thanks, Saïvann!

To fit in with the new workflow, I'm going to delete my
harding/bitcoin.org repository (which is forked off of
saivann/bitcoin.org) and create a new harding/bitcoin.org repository
based off of bitcoin/bitcoin.org. (I'll do it as soon as I make sure no
important data will be lost by doing so.)

Then I'll look into converting the style guide into markdown, adding
conventions we've agreed on since it was last updated, and then putting
it on the bitcoin/bitcoin.org wiki.

-Dave
--
David A. Harding