Sandboxes have been developed with the goal to lower the barrier for testing patches for Koha.
You can set up a sandbox with a current development version of Koha, sample data and the patches of a bug applied for you. Once you have finished testing, you can use a form to 'sign off' on the patches and move the bug report to the 'Signed off' status from where it will continue into QA.
The code of the sandboxes and documentation on how to set them up has been released under GPL and can be found in the Koha Community gitlab account.
If you encounter a problem with these sandboxes, please send an email to sandboxes at biblibre dot com or ask on the IRC channel.
If you encounter a problem with these sandboxes, please contact khall on the IRC channel.
If you encounter a problem with these sandboxes, please send a mail to sandboxes at ptfs-europe dot com or contact Martin Renvoize (aka ashimema) on the IRC channel.
Documentation and Howtos
There are some great tutorial videos that explain the whole process:
- Koha sandbox demo (10:39) (15 October 2018)
- ByWater Solutions Town Hall on Koha Sandboxes (22:38) (11 December 2018)
- ByWater Solutions on Koha Sandboxes (50:09) (27 January 2020)
- How to sign off on a bug in Koha (10:32) (05 December 2019)
Step by step
Step 1: Select a bug to test in Bugzilla
Bugs in Bugzilla can be bug fixes, small enhancements or complete new features. As there is always a lot going on, selecting a bug can take some time.
You don't need an account to search in Bugzilla, but in order to make status changes and to comment, you will have to register with an e-mail address.
An easy way to see a list of all bugs waiting for sign-off is using the link from the Koha Dashboard.
You can also create a list of all bugs in the 'Needs Signoff' status by using Bugzilla's Advanced search. Just click on 'Needs Signoff' in the status field and start the search.
The component column will give you an idea about the area in Koha this bug applies to. Templates bugs are often a good place to start with sandbox testing.
Once you have found a bug you'd like to test, note the bug number for the next step.
Note: There are some limits to sandbox testing. Things that cannot be tested currently include:
- Running cron jobs
- Running unit tests (QA will ensure they are run, so you can skip them in test plans)
Step 2: Set up a sandbox
- Pick one of the sandbox providers above
- Click on the Create link on top of the page
- You will see a form with many options, but for a minimal setup, you only need to fill in a few of those marked with *.
- Your name*: If you end up signing off on a bug, this will be used as the name in your sign-off line.
- Your email*: This is the e-mail address that will be used in your sign-off line, when you decide to sign off on a bug after testing.
- Sandbox name*: Name your sandbox using lower case letters and numbers only.
- Bug number: Enter the numeric bug number of the bug you want to test. This can be left empty if you want to start testing without the patch set first or just want to get a peek at the latest development version.
- Marc flavour: Possible options here are MARC21, UNIMARC and NORMARC. The MARC flavour you pick will affect the configuration, sample data and index configuration.
- Git remote & branch: If left empty the latest development version plus the patches from Bug number will be used. This allows to test bugs where the patches are not attached to Bugzilla for their size, but are on a remote branch of the developer. It also allows to set up a sandbox with a very specific Koha version.
- Description: optional field to make some note about what this sandbox will be used for.
- Safety question*: What was the world's first open source ILS? - We assume you know the correct answer, otherwise refer to the hint below the field :)
- Click Submit
- The Status column will first read Provision pending while the installation with your selected options is built on the server. Refresh the page after a bit and when it reads Provisioned your sandbox is ready to go.
Step 3: Login and testing
- You can now use the buttons to Staff and OPAC interface of your created sandbox from the management page. Logins and passwords are listed for each provider above.
- Start testing referring to the test plan (and beyond). If things look a little odd and something went wrong while applying the patch, you might be able to spot it in the Koha Git log available in the Logs pull down.
- If you run into problems, please add a description of it as a comment in Bugzilla and set the status to Failed QA. This can also be used if there is no test plan or if you are stuck on something to get the developer's attention.
- If everything is working right and looking good, please add your sign-off!
Step 4: Sign-off
- Return to the Sandbox management page. Select Sign-off patches from the Actions pull down on the right.
- Your name: your name. It will be part of the sign-off line added to the patch files.
- Your email: your e-mail address. This will also be part of the sign-off line. Together with your name this information will be used for building the release notes and for the Dashboard.
- Bug number: the number of the bug that you applied the patches from earlier on creating the sandbox.
- Number of patches to sign: this can be a little tricky. Often times it will be just 1, but there are bugs that can have a lot of patch files attached. In this case, count the attachments marked as patch in the table on top of the bug description in Bugzilla and enter the number here.
- Anti-spam: Just enter Koha here.
- Important: At the moment signing off from the sandbox will attach the patch with your sign-off line, but it won't change the status to Signed off. Please do so manually in Bugzilla, so that it will be moved into the queue of the QA team!
Tips and tricks
Testing sending emails
If you want to test a bug where you have to check an email being sent, you must specify a valid e-mail address in the system preference
But because the sandboxes do not actually send out e-mails, you will need to check two places depending on the Koha feature:
- sending a cart via email
- serial issue claims and acquisitions claims for late orders
- email order feature
- serial alerts: when you subscribe to get an email of a new serial issue
- complete this list if something is missing
For these go to the sandbox management interface => logs => koha mail log
For the rest, jump to next section.
The koha mail log displays the message in a raw format that changes some characters and URLs. So you see weird stuff and are unsure, paste the content on of the email from the mail log to this decoder: https://www.motobit.com/util/quoted-printable-decoder.asp Paste the email and click decode. And then the first/top text area contains the result.
Emails put in queue for sending them periodically
Use an SQL report to view the content of the generated e-mails found in the
message_queue table. Test plans usually tell to run process_message_queue.pl to have them sent but we can directly look at the queue.
select * from message_queue;
Rebuild CSS from SCSS
Sometimes you will see soomething like the following in a patch set:
To test, apply the patch and rebuild the staff interface CSS (https://wiki.koha-community.org/wiki/Working_with_SCSS_in_the_OPAC_and_staff_client).
In this case, after spinning up the sandbox and applying the patch, go to Actions > Build CSS.