Promote documents in md-pages branch.

Promote documents in md-pages branch.

Seems that now both master branch and md-pages branch have docs/
directory, but only the latter looks to be maintained.
  https://chromium.googlesource.com/external/gyp/+/master/docs/
  https://chromium.googlesource.com/external/gyp/+/md-pages/docs/

This might be a bit confusing for users and contributors,
since they could be easily navigated to those documents in
master branch in the following steps.

  1. Search 'GYP' then be navigated to
     https://code.google.com/p/gyp
  2. Find 'Source' tab and click it to be navigated to
     https://code.google.com/p/gyp/wiki/Source?tm=4
  3. Find a new repository URL.
     https://chromium.googlesource.com/external/gyp
  4. Find a 'Hacking' guide w/o realizing that the document is
     a bit out of date.
     https://chromium.googlesource.com/external/gyp/+/HEAD/docs/Hacking.md

With this CL, hopefully users and contributors can find the
latest documents.

BUG=
R=dpranke@chromium.org

Committed: https://chromium.googlesource.com/external/gyp/+/8f3918d7408f5434f16964d68a8ce58570215f3c

[yukawa, 2015-10-12 20:03:41]

yukawa@chromium.org changed reviewers:
+ dpranke@chromium.org

[yukawa, 2015-10-12 20:03:42]

Hi Dirk.  Per your post at
https://groups.google.com/d/msg/gyp-developer/9Ph3k7n3juQ/8ge5vvSdKQAJ, I think
it makes sense to remove docs/ directory from master branch.  What do you think?

In my case, the following two pages that were out of date actually confused me
when I tried to catch up the new patch sending process.

https://chromium.googlesource.com/external/gyp/+/master/docs/Hacking.md
https://chromium.googlesource.com/external/gyp/+/master/docs/Buildbot.md

Anyway, this is just a proof of concept CL.  I'm fine with any way as long as I
can easily find the latest document.

[yukawa, 2015-10-12 20:04:35]

Patchset #1 (id:1) has been deleted

[yukawa, 2015-10-12 20:05:37]

Patchset #1 (id:20001) has been deleted

[Dirk Pranke, 2015-10-12 21:02:28]

Since most contributors probably only have the master branch checked out, it's
probably better that we
just leave these docs there and keep them in sync. (I would've normally tried to
do that but probably forgot
for this change).

Can you copy the changes from the md-pages branch back to master instead?

[Nico, 2015-10-12 21:18:59]

On 2015/10/12 21:02:28, Dirk Pranke wrote:
> Since most contributors probably only have the master branch checked out, it's
> probably better that we
> just leave these docs there and keep them in sync. (I would've normally tried
to
> do that but probably forgot
> for this change).
> 
> Can you copy the changes from the md-pages branch back to master instead?

I don't think keeping this in two branches makes this easier for contributors.
They'll still have to know about the correct branch, only now it's less clear
that there's another branch. I think having the data in just one place is
preferable.

[yukawa_g, 2015-10-12 21:32:27]

Patchset #2 (id:60001) has been deleted

[yukawa, 2015-10-12 21:47:50]

On 2015/10/12 21:18:59, Nico wrote:
> On 2015/10/12 21:02:28, Dirk Pranke wrote:
> > Since most contributors probably only have the master branch checked out,
it's
> > probably better that we
> > just leave these docs there and keep them in sync. (I would've normally
tried
> to
> > do that but probably forgot
> > for this change).
> > 
> > Can you copy the changes from the md-pages branch back to master instead?
> 
> I don't think keeping this in two branches makes this easier for contributors.
> They'll still have to know about the correct branch, only now it's less clear
> that there's another branch. I think having the data in just one place is
> preferable.

Yeah, I stand with you, Nico.  That's exactly the reason I removed the document
in
my patch set #1.

BTW, I heard that some people use git sub-modules so that 1) they can atomically
update the code and document, and 2) publish the document on their web site
without
manually copying the change.
http://blog.revathskumar.com/2014/07/publish-github-pages-using-git-submodule...

I'm not sure if this works for us though.

[yukawa, 2015-10-12 21:57:47]

On 2015/10/12 21:47:50, yukawa wrote:
> On 2015/10/12 21:18:59, Nico wrote:
> > On 2015/10/12 21:02:28, Dirk Pranke wrote:
> > > Since most contributors probably only have the master branch checked out,
> it's
> > > probably better that we
> > > just leave these docs there and keep them in sync. (I would've normally
> tried
> > to
> > > do that but probably forgot
> > > for this change).
> > > 
> > > Can you copy the changes from the md-pages branch back to master instead?
> > 
> > I don't think keeping this in two branches makes this easier for
contributors.
> > They'll still have to know about the correct branch, only now it's less
clear
> > that there's another branch. I think having the data in just one place is
> > preferable.
> 
> Yeah, I stand with you, Nico.  That's exactly the reason I removed the
document
> in
> my patch set #1.
> 
> BTW, I heard that some people use git sub-modules so that 1) they can
atomically
> update the code and document, and 2) publish the document on their web site
> without
> manually copying the change.
>
http://blog.revathskumar.com/2014/07/publish-github-pages-using-git-submodule...
> 
> I'm not sure if this works for us though.

Ah, I realized that the article I pointed to was talking about a bit different
approach.
But anyway, keeping documents in two different branches doesn't sound like a
long term solution.

So my proposal is:

Step 1:
  As a really short-term fix, update docs/ in master branch as Dirk suggested. 
Otherwise it continues confusing people.

Step 2:
  Unify the documents into one branch.  It's nice if we can update the source
and document at the same time.

Thought?

[Dirk Pranke, 2015-10-12 22:15:41]

I guess I'm fine w/ deleting the files on the master branch.

Keeping the docs *only* on the master branch won't work, because the
'gyp.gsrc.io' domain
can only look at the md-pages branch.

This basically mirrors what GitHub does, and I've often wondered how people deal
w/ this issue there as well.

[yukawa, 2015-10-12 22:22:58]

Patchset #2 (id:80001) has been deleted

[yukawa, 2015-10-12 22:25:12]

On 2015/10/12 22:15:41, Dirk Pranke wrote:
> I guess I'm fine w/ deleting the files on the master branch.

OK, reverted new patch sets.  PTAL on the patch set #1?

[Dirk Pranke, 2015-10-12 22:26:15]

lgtm

[yukawa, 2015-10-12 22:27:21]

Committed patchset #1 (id:40001) manually as
8f3918d7408f5434f16964d68a8ce58570215f3c (presubmit successful).