# Copyright (C) 2012, 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

(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

(2) you are working with the 'parrot-docs4' repository in which to archive the
previous Parrot documentation release.[2] 

=back

=head2 Get the 'parrot.github.com' and supporting 'parrot-docsx' repositories

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

=over 4

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

C<git clone git@github.com:parrot/parrot-docs4.git>

=back

=head2 The 'parrot-docsx' repository

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

=over 4

C<git checkout gh-pages>

=back

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

=over 4

C<git branches>

=back

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

=over 4

C<mkdir 4.0.0>

=back

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

=over 4

=item 1

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

=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 C<docs/> directory to the newly created directory in 
the C<parrot-docs4> repo.

=back

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

=over 4

C<git add .>

C<git commit -m "Commit all of the 4.0.0 documents to the repo."> (or some
such)

=back

And, lastly,

=over 4

C<git push origin gh-pages>

=back

You are done with the 'parrot-docsx' repository.

=head2 The '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 'parrot.github.com' repository. To
accomplish this,

=over 4

=item 1

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

F<README.md>;

F<README.pod>; and

F<index.html>; and

F<releases.html>.

=item 2

After saving the above files, the simplest way to proceed is to delete all of
the files in '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,

=over 4

C<git add .>

=back

and

=over 4

C<git commit -m "Remove the previous release's documents."> (or some such)

=back

=item 3

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

=item 4

Add and commit these changes to '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 '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

=over 4

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

=back

to read

=over 4

<title>Parrot 4.1.0 - Home</title>

=back

and also edit the line

=over 4

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

=back

to read

=over 4

<br>Parrot version 4.1.0            </div>

=back

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

=over 4

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

=back

to read

=over 4

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

=back

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-docs4' repository. For example, copy the line,

=over 4

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

=back

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

=over 4

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

=back

=back

Save your edits.

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

=over 4

C<git add .>

C<git commit -m "Versioning updates"> (or some such message)

C<git push origin master>

=back

It will take anywhere from one to ten (or, occasionally, even fifteen) minutes
for 'parrot.github.com' to rebuild. Once it does, you need test your updates.
You may do so by navigating your browser to 'http://parrot.github.com' and
verifying your changes.  Also, please ensure you test the link to the archived
documents in the 'parrot-docs4' repository.

If everything works correctly, congratulations, you're done with both the
'parrot.github.com' and the '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
v4.x.x and you do not have, for example, a 'parrot-docs5' repository, you will
need to contact an "owner" and ask him or her to create a new repository.  You
will, then, need to follow all of the steps outlined in Github's gh-pages guide
at '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<4.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-2012, Parrot Foundation.

=cut
