Chapter 8 SOLES development
8.0.1 Getting involved
To get involved with the SOLES development team, it is recommended that you familiarise yourself the SOLES R package, GitHub, Zenhub, R documentation, and R package development. You don’t have to be an expert in all of these areas at first! Often the best way to learn is by doing (and failing, repeatedly!). We have listed some relevant resources below for more targeted training across different areas. There is a difference between using the SOLES R package to set up a workflow and SOLES dashboard and committing time to actively working on the package. If you have capacity to actively contribute and take on SOLES development tasks, you are very welcome to join the Sprint meetings and SOLES development team. If you want to use SOLES as a tool and do not have capacity to work on new features, you are welcome to join the SOLES update meetings for ongoing support to ensure your SOLES is up to date and in line with the latest developments. These groups have a flexible membership, please indicate your preferences and join meetings in line with this guidance.
8.0.3 Using GitHub
GitHub Basics
For code management and collaboration, we rely on GitHub for version control, enabling us to track changes and collaborate effectively. GitHub is a widely used platform that operates on Git. Users store their code in repositories, which can be public or private. GitHub’s collaborative tools allow developers to propose changes through branches, enabling modifications without affecting the main codebase. Pull requests initiate discussions and reviews, leading to changes being merged into the main branch.
GitHub Resources:
Github Basics
Skills Intro Course
Using GitHub for SOLES
If you wish to collaborate on an existing SOLES project, you must open RStudio via the juniper server and follow these steps:
1. Open a New Project
2. Click on Version Control
3. Choose Git
4. Get the GitHub URL for the project you wish to work on. Save to your Projects folder.
5. Create a New Branch
6. Name your New Branch and sync with remote.
Now that you’re all set up, feel free to start working on your own branch of the project. Remember to regularly commit your changes and push them as needed. Once you’re satisfied with your pushed changes, you can create a pull request, which will undergo review before being merged into the main branch.
8.0.4 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 two-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” on the board, which tell us the status of an issue:
Epics - These are for larger projects, each containing multiple smaller issues.
New Issues - New issues which will likely be given a home 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 - Things we are currently working on.
Review/QA - Work which we have completed and want to pass on to Kaitlyn for review.
Closed - Issues which have been completely finished and Kaitlyn has reviewed.
Within the ZenHub issues themselves, you 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. This is vital as it can be challenging to recall the specifics of a task, especially if you weren’t the one who initially created the issue.
8.0.5 SOLES development processes
To actively contribute to SOLES, it is recommended that you join the Sprint planning and Sprint update meetings. At the Sprint planning meetings, you will have the opportunity to make suggestions for features you would like to work on or take on outstanding tasks from ZenHub tickets. If you are working on a new feature or collection of related features, it is recommended that you create a new branch in GitHub. If you have any support, please raise this in the Sprint update. If you have specific questions that can be easily addressed, create a discussion topic on the SOLES GitHub and provide a description of the coding problem you are facing, ideally with some reproducible code examples. If required, you can arrange a 1:1 meeting with Sean to discuss a complex coding / logic problem. While working on the new branch, make sure to commit your changes as often as possible with useful commit messages and push those changes to the branch. If you finish a coding task on the SOLES package, this requires review before your branch can be merged into the main branch. Follow the steps below to complete coding task and integrate it into the SOLES package. 1. Re-load the SOLES package with your changes and check that the package builds as expected without any Errors or Warnings. Notes are acceptable. 2. Push all of your commits to the branch. 3. Create a pull request on GitHub with the branch you have worked on. 4. Move the ticket on ZenHub to the Review/QA section to flag that you are waiting on code review and integration. 5. An independent member of the SOLES development team (usually Kaitlyn or Sean) will review this within 1 week and provide feedback where necessary. 6. Make further changes (if required) 7. Your code will now be integrated into the package
8.0.6 Sprint meetings
We have Sprint planning meetings every second Monday at 9am (UK time) and Sprint update meetings every Thursday at 3.30pm (UK time). If you would like to join these meetings, please let Kaitlyn know and she will add you to the Teams meetings.
8.0.7 SOLES update meetings
SOLES update meetings are to ensure that everyone who is not actively working on SOLES coding tasks is up-to-date on recent developments and new features. This is also a space for those who are the domain experts leading different SOLES to raise blockers or concerns. If anyone would like to raise a topic of discussion e.g. propose a new research idea using SOLES, indicate the need for a new feature, or discuss external opportunities and collaborations, they are very welcome to do so here.