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)
(2)

Get the parrot.github.com and supporting parrot-docs' 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-docs6. 6 for major version 6. 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-docs6.git

The 'parrot-docsx' repository

cd to the parrot-docs6 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 6.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-docs6 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

    git tag | grep RELEASE | tail

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-docs6 repo.

Once the contents of the docs/ directory are in the newly created directory in 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 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
    index.html
    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 .
    git commit -m "Remove the previous release's documents."

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-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.

Finally, you are now ready to commit and push your updates to 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 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-docs6 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 v6.x.x and you do not have, for example, a 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 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, 6.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.