Caring for your code: how a shared standard lifts us all.
I’m a very measured person. Not prone to grandiose statements or outbursts (the occasional Slack (╯°□°）╯︵ ┻━┻ aside).
This view of myself waivers when I get onto the topic of open source software and standards. My evangelism on the subject can reach fever pitch and makes me wonder if I’ve been brainwashed by a cult. But my analytical self is certain there are sensible reasons for this. Sensible reasons, too, for why I’m excited about the publishing of the Victorian Government’s digital standard for open source.
I was a technical and community consultant during the development of this digital standard, along with other members of the VPS and open source industry. We shared our knowledge and experience to provide a Victorian context and practical considerations. The digital standard formalises a process of sharing that VPS projects can converge on.
It’s not a hard line though. No hell fire for not adopting it. But there are plenty of reasons why you should.
Why share?
Across all sectors the use of open source has been piecemeal but gaining in general acceptance over time. The publishing of the Victorian standard comes as formal recognition and as recommendation. It’s formal recognition of the importance of sharing. Sharing amongst colleagues and sharing with the wider community.
It is a recommendation for sharing outcomes, as well as development. This provides benefit to the entire community. For the public sector the most important benefits are transparency, engagement and empowerment.
Software or code is most often thought of as a product. But what about code as knowledge? For the same reason that communities accept public libraries as an undeniable right to knowledge, we should consider the outcomes of our work as knowledge that belongs in the public domain. That is what is being achieved by publishing these standards.
Code developed by the public sector is knowledge that empowers the community it represents.
It provides engagement with private industry. That provides opportunities for the development of services whose need was previously unrecognised or that the public sector couldn’t provide for.
And it empowers all to contribute. Putting the product out there allows anyone with an issue to find help to solve it.
All for free! Free: as in lunch.
Conditions on open source use
There are caveats to what entitlements you have when using an open source project.
Those conditions are set by the licence that is used by the project.
The Victorian standard doesn’t recommend what licence to use because every project is different. And there’s a licence to suit every scenario.
You also take on obligations when deciding to use or publish open source projects. The standard helps to bring these into focus for those new to open source.
The road to open source — options for managing contributions
So, how to move towards nirvana? How do we get to the point of sharing our efforts and nurturing the community to build them?
In the digital context, we need to start with something in a digital format. It could be scaffolding for a new project, a Victorian Government API Design Standard or possibly the digital standard itself at some point.
And in the digital context we can share and collaborate on digital materials wherever we are. Even during a pandemic.
To manage contributions from a community of remote users the project uses a distributed version control system (VCS). This makes it possible to acknowledge contributors. And with a remote repository makes disaster recovery possible.
In the open source community the VCS with the greatest number of repositories is Git. That popularity brings with it plenty of choice to host a project. GitHub is one option. Another is GitLab, an entirely open source project that offers self-managed versions to the community.
These projects provide the community with the ability to report and discuss issues. The more active the community the more discussion and it’s those who take action and contribute that lead to change.
Victorian Government projects use a variety of services. One example is Single Digital Presence (SDP) Digital, Design and Innovation, Department of Premier and Cabinet Victoria on GitHub. Anecdotally I’ve heard of both Atlassian’s BitBucket and GitLab being used in other Departments.
Consolidating into a single organisation would expand the visibility of projects and contributors. Improved exposure increases the number of cross team contributions. It provides specialists an opportunity to provide input across projects and spreads knowledge across the sector. A revision to the standard could see this refined to a recommendation of an actual service.
Contributing and accepting work
The contribution process generally follows these steps:
1. Open an issue providing detail about reproducing the issue and expected behaviour
2. Community confirms the issue
3. Community discusses solution direction
4. A contributor commits a fix or enhancement and authors a pull request (PR)
5. The PR is reviewed and changes are either requested or the PR is approved, ready to be merged into the project.
A common standard requires checks to be performed before work is merged into the project. This could be a code review or automated tests to ensure existing functionality doesn’t break.
Open source etiquette
At the point of review, common social etiquette is vital. Constructive criticism furthers the project and benefits the developer it’s directed at. Criticisms that are not well thought through hurt the community as a whole. They create more work and reduce enthusiasm for contributions.
As a guide there are three simple questions you can ask yourself before posting feedback:
1. Does the feedback provide direction?
2. Does the feedback improve the understanding of the parties involved in the discussion?
3. Is the feedback personal?
Putting your work out there can be very revealing, as an author it can be an anxious experience. Being able to separate criticism of code from personal criticism is an important consideration.
For these reasons its good practice to provide templates for users when opening issues or pull requests. These guide a user on what information to provide and give them a framework for how to respond. It reduces the community effort in reproducing issues and providing informed solution direction. Here’s some guidance from Github on templates. For more detail on what makes a good code review, have a look at the SDP documentation.
And then the cycle repeats, with improvements being made with each iteration.
But it’s not as simple as:
1. pull some packages
2. glue them together
3. publish
4. profit (both financial and a healthy community)
Be nice. Attribute.
If open source code is being used in a project, it needs to be acknowledged. The best way of doing this is providing that attribution in the product or project itself. One implementation that I’ve heard of used the ‘Konami Code’ on a website project. Inputting this key combination presented an overlay of the development team and the tools they used.
This acknowledgement benefits the projects you’re leveraging and draws attention to their contributors. It’s not only for karma that this practice is important, it may be a requirement of a dependency’s licence.
This attribution helps to foster engagement with the projects you’re using, drawing more contributors. Managing community is a consuming process and requires dedicated effort but the effort is rewarded in many ways.
Benefits of working this way
Community engagement returns validation of efforts through community peer review. It is also an opportunity for professional growth for developers. The more diverse the community the more perspectives that can shape the solution.
Shared workloads and the benefit of specialists focusing on their area of expertise are another benefit. Because of the complexity of most digital projects, being able to delegate tasks to a specialist is incredibly useful.
But the most important? Bigger parties. As you open up to the community you increase the number of people to celebrate major milestones with. The more the merrier.
