Submit Pull Tonight?

[David A. Harding]

Hi,

Saļvann and I are nearly done everything we planned to go for the pull
request to Bitcoin.org. Hurrah! Chris has inquired about making that
pull request before our original goal of May 15th, and I think we're
ready to do it *tonight*.

However, I will not rush the pull request if anyone wants a last chance
to review. This is your chance to say something like:

* "I plan to review. Please don't submit the pull request until I give
the all-clear."

* "I'm done reviewing. Once Saļvann and Dave have reviewed everything,
they should submit the pull request."

I'd like to hear from at least two of the following active contributors
before submitting the pull: Greg, Chris, and Mike.

* Here's the current preview: http://bitcoindev.us.to/en/developer-documentation

* Here's the last uncomitted pull: https://github.com/saivann/bitcoin.org/pull/125

And here are the things I plan to do:

* Meticulously review the combined diffs since my proofreading yesterday
looking for any sneaky last-minute mistakes.
* Merge #125 after 24:00 UTC
* Update my preview
* Final check my preview/Make sure Saļvann's preview matches
* Create final squashed commits
* Push squashed commits to bitcoin/bitcoin.org devel-docs branch
* Have Saļvann check the branch above
* Create "Developer Guide Content Improvements" bug on bitcoin/bitcoin.org
* Submit pull request

-Dave
--
David A. Harding

[Saïvann Carignan]

Great! (Waiting to hear Greg / Chris / Mike comments)

Aside for my comments on the "Describe Merge" pull request, I have one question about the suggested plan:

Re: "Create "Developer Guide Content Improvements" bug on bitcoin/bitcoin.org"

What is that for? Won't we work and comment on the pull request directly?

Saïvann

Le vendredi 9 mai 2014 18:46:32 UTC-4, David Harding a écrit :

Hi,

Saïvann and I are nearly done everything we planned to go for the pull

request to Bitcoin.org.  Hurrah!  Chris has inquired about making that
pull request before our original goal of May 15th, and I think we're
ready to do it *tonight*.

However, I will not rush the pull request if anyone wants a last chance
to review.  This is your chance to say something like:

* "I plan to review. Please don't submit the pull request until I give
  the all-clear."

* "I'm done reviewing. Once Saïvann and Dave have reviewed everything,

  they should submit the pull request."

I'd like to hear from at least two of the following active contributors
before submitting the pull: Greg, Chris, and Mike.

* Here's the current preview: http://bitcoindev.us.to/en/developer-documentation

* Here's the last uncomitted pull: https://github.com/saivann/bitcoin.org/pull/125

And here are the things I plan to do:

* Meticulously review the combined diffs since my proofreading yesterday
  looking for any sneaky last-minute mistakes.
* Merge #125 after 24:00 UTC
* Update my preview

* Final check my preview/Make sure Saïvann's preview matches

* Create final squashed commits
* Push squashed commits to bitcoin/bitcoin.org devel-docs branch

* Have Saïvann check the branch above

[David A. Harding]

On Fri, May 09, 2014 at 05:31:08PM -0700, Saīvann Carignan wrote:
> Re: "Create "Developer Guide Content Improvements" bug on bitcoin/
> bitcoin.org"
>
> What is that for? Won't we work and comment on the pull request directly?

Yes; absolutely. Any problems with the content in the pull request
should be discussed on the pull request. That quote is regarding this
part of the proposed pull request message:

To keep comments on this pull request focused, we'd appreciate it
if suggestions about possible future content or better ways to
organize this information were made on GitHub issue (FIXME) or on
the Bitcoin Documentation mailing list (FIXME), leaving comments on
this pull request only for things which should be fixed or changed
before merging.

Thanks!,

[Saïvann Carignan]

Ah, I see!

These could perhaps be opened as separate issues on bitcoin.org BTW and
we could assign them a label to keep track of devel-doc issues. This
would be easier to track each request / bug individually.

Saïvann

[David A. Harding]

On Fri, May 09, 2014 at 08:47:50PM -0400, Saīvann Carignan wrote:
> Ah, I see!
>
> These could perhaps be opened as separate issues on bitcoin.org BTW and
> we could assign them a label to keep track of devel-doc issues. This
> would be easier to track each request / bug individually.

Commenting on the pull request will be super easy for anyone already
reading it, but I don't want extraneous comments to appear there when
they might hold up merging. I thought commenting on an existing issue
would be almost as easy, so we'd have a good chance of getting people to
post their content suggestions there.

To anyone like me who tries to be respectful of developer time, opening
a new issue is a big deal. It's not something you do unless you
strongly suspect you have something important to say. I'm worried that
if we request people open new issues, they'll instead post stuff they
think might not be that important to the pull request where it'll hold
up merging.

Instead, we can have everyone post new content suggestions to the
pre-created issue, and then we can create new issues for any suggestions
we think are important.

What do you think?

[Saïvann Carignan]

Mmh, how about we point to one single place for this? I think the
mailing list is more suited for brainstorming and feedback. And we can
request people to open issues from there if some good ideas /
easy-to-implement stuff / anything that deserves to be tracked or fixed.

Saïvann

[David A. Harding]

On Fri, May 09, 2014 at 09:37:59PM -0400, Saīvann Carignan wrote:
> Mmh, how about we point to one single place for this? I think the
> mailing list is more suited for brainstorming and feedback.

I agree that it's more suitable, but the mailing list has the same
problem as opening an issue---it's significantly more difficult than
just posting a comment on the pull request. (For example, you need to
subscribe to the mailing list before posting.)

If you want, we can point them at a wiki page on saivann/bitcoin.org.
I think that's harder than posting a comment, but it's still
pretty simple.

[David A. Harding]

On Fri, May 09, 2014 at 06:46:32PM -0400, David A. Harding wrote:
> I think we're ready to [submit a pull request] *tonight*.

The (hopefully final) squashed branch has been uploaded. Here's a
comparison between it and the main Bitcoin.org repository:

https://github.com/harding/bitcoin.org/compare/bitcoin:master...devel-docs

Once Saīvann pulls that branch (link below), compiles it with Jekyll,
and compares the HTML generated against the HTML generated by Jekyll
with his saivann/dev branch, we should be ready to go. (I've done my own
diffing, and there were no differences found.)

https://github.com/harding/bitcoin.org/tree/devel-docs

All we need is to hear from any two of Chris, Greg, Mike that reviews
are finished, and from Saīvann that he's completed the HTML integrity
check described above and updated the live preview.

Thanks everyone!,

[Saïvann Carignan]

I confirm the squashed commits (ffde087) are identical to the dev branch
locally merged with master and the right commit id is used in the commit
msg (c2b8d56).

(I didn't check the HTML diff, but that's equivalent).

I just updated the live preview!

Saïvann

[Saïvann Carignan]

I think you plan will work, although I still have a preference for the
mailing list :) But not a real issue I think.

Saïvann

[David A. Harding]

On Fri, May 09, 2014 at 11:05:38PM -0400, Saīvann Carignan wrote:
> I think you plan will work, although I still have a preference for the
> mailing list :) But not a real issue I think.

I created the wiki page... and used it to also refer to the mailing
list, hopefully bridging the gap between the two suggestions to some
degree. Wiki page:

https://github.com/saivann/bitcoin.org/wiki/Content-Suggestions

The paragraph will now read:

To keep comments on this pull request focused, we'd appreciate it if
suggestions about possible future content or better ways to organize

this information were made on our [Content Suggestions Wiki Page][],
restricting comments on this pull request to only things which

should be fixed or changed before merging.

[Content Suggestions Wiki Page]: https://github.com/saivann/bitcoin.org/wiki/Content-Suggestions

Thanks!,

[Chris Beams]

> All we need is to hear from any two of Chris, Greg, Mike that reviews are finished

I'll commit to getting back about this by end of day today (Saturday, European time). Thanks!

> --
> You received this message because you are subscribed to the Google Groups "bitcoin-documentation" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to bitcoin-document...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.

[Chris Beams]

On May 10, 2014, at 9:41 AM, Chris Beams <ch...@beams.io> wrote:

All we need is to hear from any two of Chris, Greg, Mike that reviews are finished

I'll commit to getting back about this by end of day today (Saturday, European time). Thanks!

I've just given the current preview [1] a once-over, and from my perspective it's in great shape to go ahead with the pull request. While I'm sure the subsequent review will uncover specific issues here and there, I think that overall folks are going to really appreciate what they see. Congrats, Saïvann and David on everything you've done so far—this is tremendous work!

- Chris

P.S.: not sure whether you've already been doing so along the way, but I ran a link checker against each of the three pages, and there were no breakages. This test didn't account for #fragment validity, however. Perhaps that's already part of the build process?

[1]: http://bitcoindev.us.to/en/developer-guide
 

[David A. Harding]

On Sat, May 10, 2014 at 05:51:42PM +0200, Chris Beams wrote:
> I've just given the current preview [1] a once-over, and from my
> perspective it's in great shape to go ahead with the pull request.

Thanks!

> I ran a link checker against each of the three pages, and there were
> no breakages. This test didn't account for #fragment validity,
> however. Perhaps that's already part of the build process?

It's not an automatic part of the build process, but both Saïvann
and I checked anchors. (In my case, using linkchecker -a from the
command line.)

I haven't heard from Mike or Greg yet, but I'm thinking we should submit
the pull request tonight (UTC-4, about another 6-8 hours from now).

[Saïvann Carignan]

> I haven't heard from Mike or Greg yet, but I'm thinking we should submit
> the pull request tonight (UTC-4, about another 6-8 hours from now).

Unless Greg or Mike comment before that time, I also agree we should go
with the final pull request.

Saīvann