Permalink
Browse files

Move README_release.pod (and rename it to 'release_parrot_github_guid…

…e.pod') to the parrot repo.
  • Loading branch information...
1 parent 3f4c2a7 commit 6e9cbe21ade1f2ee94a50d182d1b2639a53a107e @ayardley ayardley committed Mar 11, 2012
Showing with 0 additions and 321 deletions.
  1. +0 −321 README_release.pod
View
@@ -1,321 +0,0 @@
-# Copyright (C) 2012, Parrot Foundation
-
-=pod
-
-=head1 NAME
-
-README_release.pod - Readme file on how to update the github pages of the
-'parrot.github.com' repository and the supporting gh-pages branches of the
-'parrot-docsx' repositories.
-
-=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.[1]
-
-=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 three documents:
-
-F<README.pod>;
-
-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 three files you saved earlier, I<i.e.>, 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>.[5] 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-devel - 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-devel </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">Parrot Documentation Releases (4.0.0 - 0.1.1)</a>
-
-=back
-
-to read
-
-=over 4
-
-<a href="./releases.html">Parrot Documentation Releases (4.1.0 - 0.1.1)</a>
-
-=back
-
-Save your edits.
-
-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/4.0.0/html/index.html">Release 4.0.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.1.0/html/index.html">Release 4.1.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] Hopefully, soon, we will develop a script to handle most, if not all, of
-the steps outlined in this guide. At which time we will either re-write this
-guide or eliminate it entirely.
-
-[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 them 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] 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 guide example, C<4.0.0>.
-
-[5] This next handful of steps screams out for an auto-tool, and we will write
-one soon. (But, for now, you will have to settle for the detail steps in this
-guide.)
-
-=head1 COPYRIGHT
-
-Copyright (C) 2001-2012, Parrot Foundation.
-
-=cut

0 comments on commit 6e9cbe2

Please sign in to comment.