How To Audit, Document, or Test an Islandora Release

In order to contribute code - even a single word in a README file - to Islandora, you must have a signed Islandora CLA. You can audit and test without signing a CLA, but it is still recommended.

Timeline

TL;DR

Auditing -> Islandora Code Freeze -> Release Candidate and VM -> Testing -> Bug Fixes -> More Testing -> Release!

Documentation: Throughout the release cycle.

Full:

3 months before release

• Release announcement
• Call for release team volunteers

2 months before release

• Release team sign-up closes
• Auditing
• Code freeze (only bug fixes allowed on the release branch from now on)

4-6 weeks before release

• Release candidate created; virtual machine available for download
• Testing
• Bug fixes on release branch
• Documentation: make updates for the new release to ISLANDORA/Start

Day of release

• All Blocker issues on release branch resolved
• Code released
• Release notes published
• Documentation: make copy of ISLANDORA/Start and change name to ISLANDORA/7.x-1.release

Auditing

Licenses:

1. Visit the GitHub repository of the module you signed up for by clicking on the link for each component in the release spreadsheet.
2. Check to see if there is a LICENSE.txt or LICENSE file.
3. If that file exists, click on it. Verify that it is GPLv3. This is an example of what you're looking for. Make sure that it is not a GPL AFFERO license. If the correct license is present , change your License audit cell in the release spreadsheet from 'To Do' to 'Done'.
4. If the license file doesn’t exist or needs to be updated in GitHub, either use the Google Docs Insert > Comment function to add a comment in the release spreadsheet noting what needs to be changed or create your own pull request against the current release branch and 7.x branch.

READMEs:

1. Visit the GitHub repository of the module you signed up for by clicking on the link for each component in the release spreadsheet.
2. Check to see if there is a README.md file.
3. If that file exists, click on it. Verify that it adheres to the README template and make sure the correct maintainer is listed. The maintainer should be the same as the component manager listed in the release spreadsheet. If there are different names listed for the two roles, update the README to list the component manager as the maintainer or indicate this using the Google Docs Insert > Comment function to add a comment in the release spreadsheet.
4. If the README doesn’t exist or needs to be updated in GitHub, either use the Google Docs Insert > Comment function to add a comment in the release spreadsheet noting what needs to be changed or create your own pull request against the current release branch and 7.x branch.

Testing

Testers adopt one or more modules with which they have (or plan to acquire) a good working knowledge. They obtain a copy of the release VM by either downloading it from the link provided by the Release Manager, or building their own from the same vagrant scripts, so that everyone is testing in the same environment.

To Test

• Any JIRA tickets for your module that have been marked “Ready for Test” (indicating that development on them is complete) should be tested.
  • Bugs: try to reproduce the original bug. If you can’t, indicate so in the comments and the ticket will be closed.
  • Features: try out the new feature to verify that it does what it described. If it does, indicate so in the comments and the ticket will be closed.
  • Improvements: try out the improvement to verify that it has been implemented as described. If it’s there, indicate so in the comments and the ticket will be closed.
  • Failures: ensure that the module provides adequate warnings or errors as needed when the user does not do what is expected.
• Review the documentation for your module in both its readme and one the wiki and test the functionality described. If you feel there are section missing from the documentation, open up a JIRA ticket describing the shortfalls and tag it as a Documentation ticket.
• Conduct any other testing that you see fit as a user of the module. The steps above are not a limit and we know that some testers enough experience with the module to see other avenues that should be tested.

Do not hesitate to ask for guidance on how to test a ticket if it is not clear.

Documenting

1. Change the Documentation Status to ‘In Progress’ when you begin reviewing documentation for a module you have signed up for in the current release tab of the release spreadsheet.
2. Visit the GitHub repository of the module you signed up for by clicking on the link for each component in the release spreadsheet.
   1. Compare the documentation from the module’s README file on the current release branch in GitHub to the Confluence wiki to make sure there are no contradictions. The Confluence wiki is geared towards user documentation while the readme is meant to be a more brief summary of key details, so it would be useful to include detailed documentation of how to use the module, the wiki is the place for that. You will need a Duraspace account to update the wiki. This is also your JIRA account, so it’s well worth having.
   2. The README is assumed to be the most up-to-date, so if there is a conflict about details, please update the Confluence wiki.
   3. For newly contributed modules, you may have to make a new wiki page. Please consult an existing wiki page for a similar module (Solution Pack or Utility Module, for example) for page structure. There is also a style guide for Confluence wiki pages.
3. Check the documentation against the module in action. Verify that existing screenshots match the way the interface looks now and replace them if necessary. Try to conform as closely to the original screenshot as possible. You will need to download the Release Candidate Virtual Machine for testing. An announcement about where to download the Release Candidate will be sent to the Islandora Google Group.
4. Check for any outstanding documentation tickets for the module in JIRA that need to be completed. You can search here for issues assigned to you. Much of the time, there will not be tickets for specific issues related to your modules.
5. To update the module’s README in GitHub, either use the Google Docs Insert > Comment function to add a comment in the release spreadsheet noting what needs to be changed or create your own pull request against the current release branch and 7.x branch. See the GitHub help pages for more information on how to do a pull request. Change the Documentation Status to ‘Done’ when tasks are complete.

For further information about Documentation please consider joining the Documentation Interest Group (DIG). If you have questions about documentation, you can email the Documentation Manager or the Islandora Google Group and put [DIG] in the subject line.