Move documentation repository into /docs

[mattbrictson]

TODO

• Merge documentation repo into docs/
• Turn off GH Pages for the documentation repo
• Turn on GH Pages for docs/ @ master
• Remove any remaining references to the documentation repo in the Markdown
• Recreate my 2 documentation PRs
• Mark the documentation repo as "defunct" (delete all files and put a explanation in the README)

---

GitHub recently announced that GitHub pages can now be hosted within the /docs directory of a repository's master branch. There is no longer a technical limitation that requires us to maintain a gh-pages branch or a separate documentation repo.

What does the community think about moving the existing website GitHub pages documentation into a /docs directory of this project instead?

Pros:

• Code and documentation can be contributed in a single PR
• Long term the documentation should more closely track actual Capistrano behavior
• Fewer repositories to maintain (I suspect most contributors don't even know the documentation repo exists)

Cons:

• The website will always represent the "master" version of Capistrano, so certain features/behavior will be documented before the gem itself is released

/cc @leehambley @will-in-wi

[will-in-wi]

I'm in favor of this. It'll be a pity to lose the version history on that, though…

I assume we take a snapshot of the code as it exists today and commit it to the Capistrano repo, then make one more commit to the documentation repo explaining the change?

Per the con, in the past we've added docs with a version specifier.

[leehambley]

We could use https://saintgimp.org/2013/01/22/merging-two-git-repositories-into-one-repository-without-losing-file-history/ which I've had a positive experience with.

I'm afraid however that it would completely nuke all tags, etc, since every ref after the first commit in the docu repo would be changed... :(

[mattbrictson]

OK, how about this? I spliced the entire history of the documentation repository on top of capistrano @ master. That means the capistrano history remains unmodified; all tags are still valid, etc. There are just a bunch of new commits that add docs/.

Will that work? See: https://github.com/mattbrictson/capistrano/tree/merge-docs

Or if we don't think we need to pollute the capistrano repo with the documentation commit history, we can just add docs/ with one enormous commit.

[leehambley]

Im on mobile but will try and have a look at the history andnsee if I can
live with it.

Summary: agree with the merge to docs/, would prefer keeping history if the
price isn't too high... (@matt, what command did you use to merge them?)

(Sent from my Nexus 6, please forgive typos!)

On Aug 24, 2016 03:16, "Matt Brictson" notifications@github.com wrote:

OK, how about this? I spliced the entire history of the documentation
repository on top of capistrano @ master. That means the capistrano history
remains unmodified; all tags are still valid, etc. There are just a bunch
of new commits that add docs/.

Will that work? See: https://github.com/mattbrictson/capistrano/tree/
merge-docs

Or if we don't think we need to pollute the capistrano repo with the
documentation commit history, we can just add docs/ with one enormous
commit.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#1752 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/AABKCLSDE4bq4AfPhAxwI_-C6VPgof1xks5qi5tqgaJpZM4Jo9LE
.

[will-in-wi]

I'm not sure which I prefer, but it wouldn't be a bad option to simply pull the docs in with one large commit, and have the commit message reference the old repository. That way, anyone trying to figure out the history of a change can jump over to the old repo.

[will-in-wi]

I went through the merge-docs history and I really like this solution. It seems like the docs tree is spliced alongside the existing tree, but since the actual introduction of code happens in the merge commit, the original history is not rewritten.

👍

[leehambley]

• history not rewritten

this addresses the only worry I had... I'm not too precious about preserving doc history, or tags/etc so I like this solution a lot.

LGTM

[mattbrictson]

what command did you use to merge them?

In my working copy of the documentation repo, I created a branched called docs-subdir where I moved everything into a docs/ subdirectory.

Then in my working copy of the capistrano repo, I added my documentation working copy as a remote called docs-temp, and git fetched it. This was the magic:

git remote add docs-temp ../capistrano-documentation/.git
git fetch docs-temp
git merge docs-temp/docs-subdir --allow-unrelated-histories
          ^         ^           ^
          |         |           needed because I'm merging two different repos
          |         |           with no shared history
          |         | 
          |         branch of the documentation repo where I've moved 
          |         everything into docs/       
          |
          remote pointing to my local documentation repo

Inspired by this post I found: https://ahmadatwi.me/2016/04/07/how-to-move-a-git-repository-to-subdirectory-of-another-repository/

[mattbrictson]

I created a PR: #1753.

[mattbrictson]

There's also the problem of open issues and PRs in the documentation repository. Those will need to be closed and manually moved to the main capistrano repository, I guess?

[will-in-wi]

Yeah... Or do a sweep of merges and then walk through the process again.

[leehambley]

Maybe Github support will migrate them for us?

Lee Hambley
http://lee.hambley.name/
+49 (0) 170 298 5667

On 24 August 2016 at 17:40, William Johnston notifications@github.com
wrote:

Yeah... Or do a sweep of merges and then walk through the process again.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#1752 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/AABKCNMlZHLXak2P5Jxmharl__31M_uiks5qjGX3gaJpZM4Jo9LE
.

[will-in-wi]

Maybe... I'm not sure how, as it would be a nasty merge conflict. And I assume the commit IDs for the docs have changed.

[mattbrictson]

Looks like the only 2 documentation pull requests are mine; I can recreate those if necessary. As for the issues, I like the idea of GitHub support doing it for us. 😀 Can you take the lead on that, @leehambley?

[leehambley]

Looks like the only 2 documentation pull requests are mine; I can recreate those if necessary. As for the issues, I like the idea of GitHub support doing it for us. 😀 Can you take the lead on that, @leehambley?

Done (moved them manually using a tool from Google)

[mattbrictson]

@leehambley Thanks for moving the documentation issues! I created a new documentation label and tagged all of the issues you migrated.

[mattbrictson]

Docs have been merged! I think there are a few more tasks, which I will add to this issue as a checklist:

• Turn off GH Pages for the documentation repo
• Turn on GH Pages for docs/ @ master
• Remove any remaining references to the documentation repo in the Markdown
• Recreate my 2 documentation PRs
• Mark the documentation repo as "defunct" (delete all files and put a explanation in the README)

[mattbrictson]

All done! The website is now being published from docs/. 🎉