Chapter 9 SyRF Development
9.1 Getting involved
We have a number of roles within our SyRF team- focussing on development, design, testing and support (help desk, user guide and help videos). To get involved with the SyRF development, design, testing or support team get in touch via helpdesk@syrf.org.uk
9.2 Need help with SyRF?
If you encounter an issue with the SyRF software please check the user guide (https://help.syrf.org.uk/) or send an email to the SyRF help desk at helpdesk@syrf.org.uk.
Please include the following details in any email request sent to the SyRF help desk to help us diagnose and resolve your issue as quickly as possible:
- Email address associated with your SyRF account (specifically, the SyRF account that you were using when you encountered any issue that you want to report).
- Summary - Briefly describe the issue you are experiencing.
- URL - If the issue is related to a specific webpage or functionality, please provide the URL.
- SyRF Project ID.
- SyRF Systematic Search ID.
- Steps to Reproduce - List the steps you took that led to the issue. Be as specific as possible and include any relevant actions or information.
- Expected Behavior - Describe what you expected to happen instead of encountering the issue.
- Actual Behavior - Describe what actually happened when you encountered the issue.
- Additional Information - Include any other relevant information that might help us understand the issue, such as:
- Screenshots
- Browser and operating system information
- Error messages (if applicable)
- Any specific configurations or settings.
You will receive a response with a ticket number to track the issue you reported. It is important to contact the help desk to ensure that the report is recorded and added to the development team’s task list. Please do not reach out to individual developers or the general CAMARADES Teams chat as your report can easily be missed if reported via another channel.
Crash Reports
If you encounter a crash whilst using SyRF, please fill out the relevant details in the pop up window that appears - these crash reports are passed onto the development team and are invaluable for helping us identify issues efficiently and resolve them quickly.
9.3 New to SyRF?
We recommend making an account and getting stuck in by creating a test project. See how-to videos: https://help.syrf.org.uk/videos.html
Demo
Are you new to SyRF and would like to demonstration? Join the CAMARADES Berlin drop-in sessions, every Monday at 11am UK time, with Alex from CAMARADES Berlin and ask away: https://www.bihealth.org/en/quest/service/service/systematic-review-methods-consultation-hour
9.4 GitHub
GitHub Basics
For code management and collaboration, we rely on GitHub for version control, enabling us to track changes and collaborate effectively. https://github.com/camaradesuk/
Main Repos of interest:
- syrf-web
- syrf-api
- jxc (Jenkins-x repo)
9.5 Using ZenHub
ZenHub is a project management tool specifically designed for software development teams that use GitHub. It serves as our go-to platform for managing our agile working sprints, each sprint spanning a four-week period. Within this framework, we create tickets/issues which contain detailed information regarding specific tasks for completion. We then move these issues around our Zenhub board depending on the urgency or status or the task. We will often review the urgency/status of tasks during our sprint meetings. There are a few different “pipelines” or column on the board which we use, which tell us the status of an issue:
Epics - These are for larger goals/features, each containing multiple smaller issues.
New Issues - New issues which will be considered at our next sprint meeting.
Icebox - This is for ideas which we hope to work on in the future, and are not urgent.
Backlog - Tasks which we plan to work in the near future.
Sprint Backlog - This is for tasks we plan to work on during the current sprint.
In Progress - Tasks we are currently working on.
Review/QA - Work which we have completed and want to pass on to another team member for review.
In Staging- Issues which are currently in the development version of SyRF. They may be awaiting testing or are ready to be launched upon the next release. **
Closed** - Issues which have been completely finished and published to the live SyRF.
Within the ZenHub issues themselves, we have the ability to provide a title, description, label, assignee, sprint assignment, and an estimated completion time. It’s crucial to complete as much of this information as possible, with particular emphasis on the description field.
9.6 SyRF Development Processes
To meet our goals, the SyRF team currently has a number of meeting to ensure the smooth running of the maintenance and development process. You should only attend SyRF meetings regularly if you are actively involved in the team. You may be asked to attend one off meetings, such as for testing a new feature.
9.6.1 Sprint Meetings
In our current workflow we have Stand up meetings on Monday, Wednesdays and Thursdays at 9:40am, design meetings every Tuesday at 12:30pm (UK time), Mid-sprint meetings on Tuesdays at 12pm or 1pm (UK time) or every four weeks we have a combined Sprint Retrospective, Review and Planning meeting on Tuesdays at 12pm-1pm (UK time).
- Stand up meetings (10 minutes) - Here we discuss: progress we have made since our last catch up, what we are planning on achieving today, any blockers/challenges and we check progress against our Sprint Goals by consulting the Burndown Chart in ZenHub.
- Mid-sprint meetings (30 minutes) - Here we review email issues as a team, check progress by reviewing remaining issues for sprint & consulting Burndown Chart. During this meeting each member states how progress is going (without detail) and plan if any help is needed. We also consider any outstanding issues, review the “Ideas to be Discussed” Zenhub column and plan any necessary additional meetings.
- Sprint Retrospective meetings (10 minutes) - Provide an opportunity to improve the sprint process by reflecting on what has gone well or badly during the previous sprint. At this meeting each person presents one pro and one con of the sprint process.
- Sprint Review meetings (30 minutes) - An opportunity for each member to report on how they did in achieving the sprint goal with a demonstration if needed and to discuss what was not achieved. We also review email issues (ensuring email status is updated in the User Ticket Triage column of the ZenHub board), review the User Ticket Triage column of the ZenHub board and assign work items, review bugs, decide if any other discussion topics (major issues/decisions etc) require additional meetings over the next sprint and move incomplete items to next sprint or backlog.
- Sprint-Planning meetings (20 minutes) - Allow us to set our goals and tasks for the next sprint. Firstly we set the sprint goal (aims we want to achieve by the end of next sprint) and record this on our SyRF GitHub Discussion. We then decide on which tasks should be assigned to the sprint based on goal and move corresponding items from backlog to sprint backlog. We add work items related to User Ticket Triage items, bugs and related work items to the sprint. We then finalise the tasks for the sprint, ensuring that total work is less than capacity.
- Feature Spec meetings (30mins-1hr) - This meeting allows us to think through the behaviour of a new feature. We map out what the minimum functional requirements, what the “nice-to-haves” are and what are add-on functionality that we plan to add in a future iteration. We also review the user requests about a given features. We may also rough-sketch some wire-frames of what the feature may look like to assist design team members. Feature spec meetings are usually held at the beginning of designing a feature, and may be held multiple times over the course of the feature creation.
- Bugs and Review Triage meetings (1hr) - We review bugs that have been reported by users on Sentry or via email. This meeting enables us to assess what work may be needed to investigate and fix a reported bug. We also review and respond to user emails to ensure that we have the most up-to-date information about an issue to proceed.
Meeting notes are recorded in Github: https://github.com/camaradesuk/syrf-web/discussions
9.6.2 SyRF Design Meetings
We create designs of the user interface prior to coding the front-end. This enables the SyRF team to refine the functionality, look and feel of a feature prior to development work starting. Design work for SyRF is carried out in an online tool called Figma. Designers work from a Feature Spec set by the team and present their design work at design meetings where feedback is given. Designing features on figma is an interactive process, we welcome crestivitiy and constructive feedback during these design rounds, so we can design the best product in the end. This is why we keep the users in the focus and design according to Material Design Principles.
Link to figma training.
Link to Material Design Principles reading.
9.6.3 SyRF Testing
It is important that any feature or update we have created for SyRF undergoes user testing. This is to make sure that the new feature work as expected prior to being released.
Testing usually occurs on a test version of SyRF, which we call “Staging”. “Staging” is a complete copy of SyRF.
You may be invited to a SyRF testing session. During the testing session you will be asked to carry out some typcial work-flow activities in SyRF. These instructions are usually given verbally. You may be asked to share your screen during these sessions. We value feedback from all testers during these sessions, whether you are new to SyRF or an experienced user, and you may be invited to a session specifically because of your experience level. All SyRF testing sessions are recorded so we can go back and ensure that every bug or unexpected behaviour encountered during the session is fixed.