docs/project/release_parrot_github_guide.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.
The purpose of this document is to supplement the release manager guide, 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, tools/release/parrot_github_release.pl has, largely, superceded the functionality contained within this document. See docs/projects/release_manager_guide.pod and tools/release/parrot_github_release.pl.
This document makes two assumptions:
(1) you are the release manager and are working on
Section Xof the release manager guide ('/docs/project/release_manager_guide.pod'). Specifically, this document assumes you have already ran
(2) you are working with the 'parrot-docs4' repository in which to archive the previous Parrot documentation release.
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:
git clone email@example.com:parrot/parrot.github.com.git
git clone firstname.lastname@example.org:parrot/parrot-docs4.git
cd to the
parrot-docs4 directory and
gh-pages branch of the repo:
git checkout gh-pages
You may confirm the
gh-pages branch with the following command:
Next, make a new directory in which to house the old documentation. For example,
If you still have a copy of the previous release of Parrot's documentation,
i.e., all of the documents 'docs/' directory,
to include the html-ized documentation,
you can just copy the entire contents of
'docs/' to the newly created directory in the,
in this example,
you will need to do the following:
- Obtain the
Tagof the previous Parrot distribution at
- unzip the distribution into a temporary working directory;
perl Configure.pl on the distribution;
make html; and
- copy the contents of the
docs/directory to the newly created directory in the
Once the contents of the
docs/ directory are in the newly created directory in
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."(or some such)
git push origin gh-pages
You are done with the 'parrot-docsx' repository.
After completing the above, it's time to move the new docs, i.e., the present release documentation, to the 'parrot.github.com' repository. To accomplish this,
in some temporary location,
the following three documents:
- 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 .git directory and the .gitignore file,
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."(or some such)
- Next, copy all of the files and directories in 'docs/' in the newly installed distribution of Parrot to 'parrot.github.com' and
- Add and commit these changes to 'parrot.github.com'.
- Copy the three files you saved earlier, i.e., README.pod, index.html, and releases.html, back to 'parrot.github.com'.
Now, you need to hand-edit both index.html and releases.html. Open 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>
<title>Parrot 4.1.0-devel - Home</title>
and also edit the line
<br>Parrot version 4.0.0-devel </div>
<br>Parrot version 4.1.0-devel </div>
You also need to update the text accompanying the link to
<a href="./releases.html">Parrot Documentation Releases (4.0.0 - 0.1.1)</a>
<a href="./releases.html">Parrot Documentation Releases (4.1.0 - 0.1.1)</a>
Save your edits.
Next, open releases.html in your editor and make the following edits:
- Edit the header and footer, just as you did above in index.html.
- Copy and paste a new list element to point to the earlier release you archived in the 'parrot-docs4' repository.
copy the line,
<li><a href="./parrot-docs4/4.0.0/html/index.html">Release 4.0.0</a></li>
and paste it in as the first element of the list. Edit it to read,
<li><a href="./parrot-docs4/4.1.0/html/index.html">Release 4.1.0</a></li>
Save your edits.
Finally, you are now ready to commit and push your updates to 'parrot.github.com':
git add .
git commit -m "Versioning updates"(or some such message)
git push origin master
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!
 For the present, we have elected to retain this document, primarily, for historical purposes and as a reference document for future release managers.
 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.
 Here, you do NOT need to worry with any optimizations when configuring Parrot because you only need the previous documentation release.
 Unless there is good reason to do otherwise,
please name the newly created directory after the VERSION of the Parrot distribution you are archiving in the repo.
in our example,
Copyright (C) 2001-2012, Parrot Foundation.