NAME

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

DESCRIPTION

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.[1] See docs/projects/release_manager_guide.pod and tools/release/parrot_github_release.pl.

Assumptions

This document makes two assumptions:

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

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

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:

git clone git@github.com:parrot/parrot.github.com.git

git clone git@github.com:parrot/parrot-docs4.git

The 'parrot-docsx' repository

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

git checkout gh-pages

You may confirm the 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 4.0.0

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, parrot-docs4 repository. If not, you will need to do the following:

Obtain the Tag of the previous Parrot distribution at https://github.com/parrot/parrot/tags;
unzip the distribution into a temporary working directory;
run perl Configure.pl[3] on the distribution;
run make html; and
copy the contents of the docs/ directory to the newly created directory in the parrot-docs4 repo.

Once the contents of the docs/ directory are in the newly created directory in parrot-docs4, 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)

And, lastly,

git push origin gh-pages

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

The 'parrot.github.com' 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,

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

README.md;

README.pod; and

index.html; and

releases.html.

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 .

and

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 four files you saved earlier, i.e., README.md, 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>

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 ./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 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. For example, copy the line,

<li><a href="./parrot-docs4/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-docs4/4.0.0/html/index.html">Release 4.0.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!

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 VERSION of the Parrot distribution you are archiving in the repo. Here, in our example, 4.0.0.

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