Using Sandboxes to sign off on bugs

by Nick Clemens on Feb 7, 2022

When libraries ask how they can help contribute to Koha, one of the ways that make the developers happiest is by testing and signing off on patches in the Koha community.

The sandbox system for Koha has been developed to make this process as simple as possible. There is a page in the Koha community wiki that goes into some more detail, but we will start on the ByWater Solutions sandboxes: https://sandbox.bywatersolutions.com/.

When you click on the link you will be shown a list of the currently provisioned sandboxes. We can start on the 'Create' page.

When you click the button you will be taken to a form that provides a few fields to fill out.

For now, you only need to concern yourself with:

• Your name/email: These fields are important as they will be used for identifying you when marking the patches as signed off.
  Sandbox
• Name/Bug number: The name is generally something simple like bug_1234 and the bug number just 1234. You can provide a more descriptive name, but it is really just for display so that you can find your sandbox on the main page once it is created. The bug number is simply the number of the bug you are testing. ( You can find a list of patches that need to be signed off on the Koha Dashboard under the bug statuses list: Needs signoff )
• You can skip everything after, down to: What was the world's first open source ILS? - this is the security question and you can find the answer on the page ;-)

Once you click 'Submit' you will be returned to the sandbox homepage where you can see your sandbox being 'provisioned'

You can refresh the page after a few minutes, and the status should say 'Provisioned'

Once it does, you can click the 'Staff' or 'OPAC' buttons and you should find yourself in a familiar place, Koha! ( Note: you are using the development version of Koha, so there may be features that you don't have in your version, it's a look into the future! )

From this point you should follow the test plan on the bug in community:
Ideally, the instructions are clear and easy to follow, but in the case they are not, feel free to ask questions on the bug. We developers don't always remember to use words that fully convey our thoughts, and arbitrarily pick different meanings for words, so never hesitate to ask for clarification.

Once you have tested to your satisfaction, you can return to the Sandboxes 'home' screen and use the 'Actions' button to choose the 'Sign off on patches' option

You will get another form, it should be pre-populated with the info from your initial form, and all you will need to enter is the 'Number of patches to sign' and a repeat of the security question from before. To get the number of patches, simply look at the bug in Bugzilla and count the number of 'Attachments' that say 'patch'

Once you click 'Submit' there will be some background magic that adds your name to the patches and sends them to the community bug. You have one last step.

Visit the bug in Bugzilla, sign in, because of course you already have an account ;-) and change the 'Status' dropdown to 'Signed off' and click 'Save changes'

Voila!

That's the basic process, but I expect there may be more questions. I answer a few below, and you can always contact ByWater for any additional info.

Frequently Asked Questions

What is signing off?

Signing off is the first step in moving a proposed patch into Koha. After a developer has written code, they write up a test plan for the new code and submit it to the community on Bugzilla. A sign off is required to tell the community that someone has tried out the new code and verified it works.

What if the patch I signed off breaks things?

The answer is simple, that's what QA (quality assurance) is for!
When signing off on a patch, you are simply saying that you followed the instructions on the patches and things happened as they were described. The QA team for Koha follows up on signed off patches and confirms that, not only do they do what is advertised, they don't break anything else, and that cases the developer may not have expected are covered. Feel free to test outside the test plan, and report breakages, but that is not required.

What if the patch doesn't work?

This does happen form time to time. It's okay, the developer will not be upset (at you) if their patch doesn't work. You can skip the sign off stage in the sandboxes, and change the status in Bugzilla to 'Failed QA'

It really is okay, especially if you tell the developer in the comments what went wrong. We ask for libraries to sign off because they use Koha differently than the developers do, and may uncover real life workflow issues that we don't see when looking at the code.

What if I don't understand this test plan?

Comment on the bug and mark it 'Failed QA', if the test plan isn't clear, the bug is not ready to be signed off. Again, a comment that explains what the problem is will help

What if I have more questions?

For questions about the patches, you can comment in Bugzilla without changing the status. Sometimes you may need to clarify something, or may wonder if the patch helps with your problem. Bugzilla is meant to be where conversations about fixes/new features takes place. You can always contact the developer directly as well if your question may be outside the scope of the bug, or contact your support provider or ByWater for more info.