# Copyright (C) 2012-2014, Parrot Foundation

=pod

=head1 NAME

docs/project/release_parrot_github_guide.pod - Parrot Github Release Guide.

=head1 DESCRIPTION

The purpose of this document is to supplement the release manager guide,
I<see> '/docs/project/release_manager_guide.pod', laying out how to publish
Parrot's documentation to the 'parrot.github.com' repository and how to
archive the previous release of Parrot's documentation in the gh-pages branch
of the supporting parrot-docx' repositories. While none of this is particularly
difficult, it is a 'bit tricky; hence, this guide.

Please note: The auto-tool, F<tools/release/parrot_github_release.pl> has,
largely, superceded the functionality contained within this document.[1]
I<See> F<docs/projects/release_manager_guide.pod> I<and>
F<tools/release/parrot_github_release.pl>.

=head2 Assumptions

This document makes two assumptions: 

=over 4

=item (1)

you are the release manager and are working on C<Section X> of the release
manager guide (F<'/docs/project/release_manager_guide.pod'>). Specifically,
this document assumes you have already ran C<make html> and

=item (2)

you are working with the F<parrot-docs6> repository in which to archive the
previous Parrot documentation release.[2] 

=back

=head2 Get the F<parrot.github.com> and supporting F<parrot-docs>' repositories

The first step is to obtain the two repositories: (1) F<parrot.github.com> and
(2) the relevant repository in which to archive the previous version of
Parrot's documentation, here, F<parrot-docs6>. 6 for major version 6. To do
this, clone the two Parrot repositories with the following commands:

=over 4

=item C<git clone git@github.com:parrot/parrot.github.com.git>

=item C<git clone git@github.com:parrot/parrot-docs6.git>

=back

=head2 The 'parrot-docsx' repository

C<cd> to the C<parrot-docs6> directory and C<checkout> the C<gh-pages> branch
of the repo:

    git checkout gh-pages

You may confirm the C<gh-pages> branch with the following command:

    git branches


Next, make a new directory in which to house the old documentation. For 
example,[4]

    mkdir 6.0.0

If you still have a copy of the previous release of Parrot's documentation, 
I<i.e.,> all of the documents F<docs/> directory, to include the html-ized
documentation, you can just copy the entire contents of F<docs/> to the
newly created directory in the, in this example, F<parrot-docs6> repository.
If not, you will need to do the following:

=over 4

=item 1

Obtain the C<tag> of the previous Parrot distribution at
L<https://github.com/parrot/parrot/tags>

    git tag | grep RELEASE | tail

=item 2

unzip the distribution into a temporary working directory;

=item 3

run C<perl Configure.pl>[3] on the distribution;

=item 4

run C<make html>; and

=item 5

copy the contents of the F<docs/> directory to the newly created directory in 
the F<parrot-docs6> repo.

=back

Once the contents of the F<docs/> directory are in the newly created directory
in C<parrot-docs6>, it's time to commit and push the updates:

    git add .
    git commit -m "Commit all of the 4.0.0 documents to the repo."

And, lastly,

    git push origin gh-pages

You are done with the F<parrot-docsx> repository.

=head2 The F<parrot.github.com> repository

After completing the above, it's time to move the new docs, I<i.e.,> the
present release documentation, to the F<parrot.github.com> repository. To
accomplish this,

=over 4

=item 1

save, in some temporary location, the following four documents:

    README.md
    README.pod
    index.html
    releases.html

=item 2

After saving the above files, the simplest way to proceed is to delete all of
the files in F<parrot.github.com>. Since you will need to keep both the F<.git>
directory and the F<.gitignore> file, C<git rm -rf *> works nicely for this.

It's a good idea to go ahead and commit the changes at this time, so execute,

    git add .
    git commit -m "Remove the previous release's documents."

=item 3

Next, copy all of the files and directories in F<docs/> in the newly
installed distribution of Parrot to F<parrot.github.com> and

=item 4

Add and commit these changes to F<parrot.github.com>.

=item 5

Copy the four files you saved earlier, I<i.e.>, F<README.md>, F<README.pod>,
F<index.html>, and F<releases.html>, back to F<parrot.github.com>.

=back

Now, you need to hand-edit both F<index.html> and F<releases.html>. Open
F<index.html> in your favorite editor and update the header and footer to
reflect the present release version. That is, edit, for example, the line

    <title>Parrot 4.0.0-devel - Home</title>

to read

    <title>Parrot 4.1.0 - Home</title>

and also edit the line

    <br>Parrot version 4.0.0-devel            </div>

to read

    <br>Parrot version 4.1.0            </div>

You also need to update the text accompanying the link to C<./releases.html>.
Edit, again, for example, the line

    <a href="./releases.html">Previous Parrot Documentation Releases (3.9.0 -
0.1.1)</a>

to read

    <a href="./releases.html">Previous Parrot Documentation Releases (4.0.0 -
0.1.1)</a>

Save your edits.[5]

Next, open F<releases.html> in your editor and make the following edits:

=over 4

=item 1

Edit the header and footer, just as you did above in F<index.html>.

=item 2

Copy and paste a new list element to point to the earlier release you archived
in the 'parrot-docs6' repository. For example, copy the line,

    <li><a href="./parrot-docs6/3.9.0/html/index.html">Release 3.9.0</a></li>

and paste it in as the first element of the list.  Edit it to read,

    <li><a href="./parrot-docs6/4.0.0/html/index.html">Release 4.0.0</a></li>

Save your edits.

=item 3

Finally, you are now ready to commit and push your updates to
F<parrot.github.com>:

    git add .
    git commit -m "Versioning updates"
    git push origin master

It will take anywhere from one to ten (or, occasionally, even fifteen) minutes
for F<parrot.github.com> to rebuild.

=item 4

Once it does, you need test your updates.
You may do so by navigating your browser to L<http://parrot.github.com> and
verifying your changes.  Also, please ensure you test the link to the archived
documents in the F<parrot-docs6> repository.

=back

If everything works correctly, congratulations, you're done with both the
F<parrot.github.com> and the F<parrot-docs> repositories

=head1 FOOTNOTES

[1] For the present, we have elected to retain this document, primarily, for
historical purposes and as a reference document for future release managers.

[2] If you are working with a release of Parrot's documentation greater than
v6.x.x and you do not have, for example, a F<parrot-docs7> repository, you
will need to contact an "owner" and ask him or her to create a new github
repository.  You will, then, need to follow all of the steps outlined in
Github's gh-pages guide at L<http://pages.github.com/> to set up the
repository.

[3] Here, you do NOT need to worry with any optimizations when configuring
Parrot because you only need the previous documentation release. 

[4] Unless there is good reason to do otherwise, please name the newly created
directory after the F<VERSION> of the Parrot distribution you are archiving in
the repo. Here, in our example, C<6.0.0>.

[5] Please note: The newly archived release will I<always> be one less than
the release on which you are presently working. That is, the release you just
cut.

=head1 COPYRIGHT

Copyright (C) 2001-2014, Parrot Foundation.

=cut
