Here at Ably we consider software development to be in our DNA.
We write and maintain a lot of code, much of it open-source, with full public visibility, and we host and manage it using the GitHub platform. The code is segmented into numerous discrete repositories, each with a specific scope and purpose.
We've been using GitHub heavily since Ably was founded in 2016, so we have plenty of history, and we're committed to the platform. It has worked well for us: we love the GitHub ecosystem, and we've learned a lot about it as we've grown together.
Audit
At the time of writing, our primary GitHub organizational unit, or org, is ably, with:
- 68 public repositories, including SDKs, common sources, tutorials, and some of our older demos.
- 125 private repositories, including service implementation, website, and infrastructure.
Additionally, we have two other GitHub orgs:
- Over 50 repositories in
ably-labs, our recently created home for tutorials and our more recently created demos. A playground. - Over 100 repositories in
ably-forks.
Conform
Developers switch between our repositories spread across our multiple GitHub orgs and they want a familiar experience in each of them. So we need to make them consistent, for our customers (app developers) and for those maintaining our codebases (team members, contractors, and external contributors).
We follow universal conventions and company standards to ensure consistency across all our repositories and orgs. We also enforce consistent workflows to manage how we work across code repositories so our working practices are predictable and organized.
Monitor
We often grant several people permission to change repository settings, and these changes (deliberate or accidental) may not be spotted for some time. Some repositories may be used infrequently; settings may drift compared to what we select to use elsewhere.
We recognize the confusion and irritation that inconsistency can cause, so we need a way to monitor settings.
GitHub clearly understands that their users have a desire to gain a bird's eye view of activity across their organizations (see their September 2021 announcement of 'audit log streaming' entering public beta). The reality is that with the current interfaces to GitHub (git clients and the browser UI), there are limitations due to all these interactions' manual nature.
Examples of things we need to monitor manually:
- Has a repository been configured correctly? We need to navigate via the browser UI to its settings page.
- Are two repositories configured the same? We need to load up two browser UIs side-by-side.
Automation
We've developed a tool to help us audit and monitor our repositories, so they conform. We've brought together a number of the technologies available in the GitHub stack, including Apps and Actions, to create an automated system to produce reports that give us visibility of where we have inconsistencies or potential issues with repository configurations. We publish the reports to a separate Github repo downstream, using markdown for simplicity and inline rendering within the GitHub browser-based interface.
The tool was designed by the SDK Team at Ably, primarily because we're the team that maintains a large portion of our customer-facing, open-source code. Essentially it's a lint tool for our repository configurations, with the primary focus - for the time being - on inspecting settings that are available to most of us only via GitHub's browser UI.
ably org.What we care about
We developed this tool to give us oversight over what we care about. We strongly feel that we should, especially with our open source work, strive to always act responsibly and with empathy for others. This means we care about others and empathize with their views ('tech needs humanity' is one of Ably's core values).
Naming / Vocabulary
We must make concerted efforts to remove non-inclusive terminology from our nomenclature. This includes the branch names we use in our repositories, especially the default branch names, for both public and private repositories.
Consistency / Principle of Least Astonishment
Developers working with Ably (as maintainers or customers) should be able to, wherever idiomatically and logically possible, seamlessly move from repository to repository with minimal friction. This means consistency in the following:
- Use of labels for issues and pull requests (#2)
- The appearance of 'Projects', 'Wikis' and 'Issues' tabs on repository home pages (#11)
- The appearance of 'Releases', 'Packages' and 'Environments' sections in the side column on repository home pages (#16)
- Presence and contents of
LICENSE(#26) - Presence and contents of
COPYRIGHT - Presence and contents of
MAINTAINERS.md - Presence and broad layout of
README.md
Guard Rails / Workflow
As a company, Ably is focused on a 'written first' approach to the way that we approach our work. An implicit principle of written first is that we aim to keep things DRY, meaning that we would rather be able to point people towards a canonical location where process-oriented instructions live. In other words, our response to a query about the way to do something should be, 'look over there, where this is documented'.
Extending this principle: where possible, we install guard rails that naturally, innately steer people onto the correct tracks, so we don't have to explicitly document a process because a switch or rule directs them.
We also use the tool to check that those guard rails are consistently configured correctly. For example:
- Allowed behavior of the merge button (#11)
- Branch protection rule for the default branch (typically
main)
Ably's solution
Ably's repository audit tool is available on Github.
We've made it open source in the spirit of our core "open for all" value, and we're keen to share what we're up to with you. It's a work in progress that we fully expect to evolve over time. You can review the issues list as that's the live, constantly updated, canonical location for plans around this tool.
You're welcome to contribute your own ideas too.
About Ably
Ably is a fully managed Platform as a Service (PaaS) that offers fast, efficient message exchange and delivery, and state synchronization. We solve hard engineering problems in the realtime sphere every day and revel in it. You can find us on Twitter or LinkedIn, and apply to join us in one of our open roles.
