How to build an open source metrics dashboard
[ad_1]
Open Source at the World Health Organization
Did you know that the World Health Organization (WHO) Was the first agency within the United Nations to establish an Open Source Programme Office (OSPO)? While such organizations already exist in large technology companies, academic institutions and governments, WHO’s OSPO was the first of its kind – a decision that has helped the institute further advance its mission by using technological solutions.
GitHub has been working with WHO since 2020, both in strengthening their internal software development processes and in supporting the creation of their OSPO. They have over 100 open source repositories from various groups, and one of their responsibilities is to ensure that their open source ecosystem is safe, reliable, and well maintained (that is, healthy). To ensure they could meet this task, they needed a measurable way to check what was going well, what needed improvement, and what they needed to keep an eye on.
As part of our Social Impact Skills-Based Volunteering program, we have made our skills available to tackle this project: by setting up a Open Source Metrics Dashboard. As we’ve worked this out, we’ve identified not only some best practices that can be applied to similar projects, but also some of the best ways to collaborate on open source projects in general.
Dashboard strategy and challenges
The first step in building the dashboard strategy was to answer the question: “What does it mean to be healthy?” We looked at the CHAOSS project of the Linux Foundation that builds metrics, metric models and software to understand the health of the open source community worldwide. We used some of their metrics as a starting point, then made a list of things that WHO’s OSPO was interested in and matched that with what would actually be computable.
When creating such dashboards, there are common challenges that you need to overcome. These include things like:
- Cost: When developing a metric, we need to consider the volume of data used, especially when designing the dashboard to ensure efficient loading.
- Data storage: We wanted to minimize dependencies for the project, so we had to get creative with how we stored the calculated metrics.
- Rate limits: Every tool has its limitations when it comes to retrieving data from GitHub’s API. We encountered certain rate limits when retrieving the required data, which forced us to reevaluate how we were retrieving the data and the amount of information we could obtain.
- Maintainability: For a small team, it is important that the tools are easy to learn, use, set up and maintain over the long term.
Workflow and architecture
How we worked
When collaborating on an open source project, you need to find ways of working that will set you up for success. This includes the best ways to work asynchronously, documenting expectations, and keeping everyone updated on progress. When creating this dashboard, there were a few things that helped ensure we all held ourselves accountable:
- GitHub issues helped us track the work of individual contributors, generate new ideas for the build, and take notes for future improvements.
- Pair programming made the whole process a pleasure and enabled us to collaborate and get feedback on work in progress.
- Monthly synchronizations with the WHO team was an opportunity for us to gather feedback and see what they were developing and how it could be useful for us. For example, in a feedback session we heard from them that they needed to show a subset of the repos to only some maintainers, so we added a topic filter to the dashboard.
- Integrated customization meant that WHO owners could easily manage and modify aspects of the dashboard in the future, and that it could also be used for other open source projects.
Building the architecture in 4 steps
When we started developing the architecture, we actually split it into two separate applications. We had the Typescript backend project that generates data and then the NextJS/React project that renders the UI of the application. At build time, we run a pipeline of functions via GitHub Actions. This pipeline:
- Retrieves data from the public GitHub API, specifically the GraphQL API.
- Transforms and aggregates the data into the desired form.
- Saves the data output in a JSON file that is filled by the backend.
- The data is then loaded into the next static JS site build, so it is available on the frontend as soon as the site is built on GitHub Pages. This is the secret sauce of the project – for small or medium sized organizations, the site will load quickly because all the data is already populated at build/load time.
This is just an example of a fairly simple workflow walkthrough, but sometimes small and powerful is the best option. It also meant we could ship it very quickly.
3 Best Practices for Open Source Development
This project helped us identify best practices that can be applied to open source projects generally. If we had to summarize this in three conclusions, they would be: build openly, configure for everyone, and adopt appropriate community branding.
1. Build outdoors
When it comes to open source, this is how you should start building from the beginning. You’ll thank yourself later when you start planning and architecting the tasks, because it allows you to break your project into manageable pieces. You can focus on some of the core work while the community can grab the easy-to-achieve goals while they get to grips with the project.
To ensure your community runs smoothly, it is important to establish and enforce strict coding practices and security rules. For this project, we enforced the desired styles by Linters and formatters that allowed people to get on board quickly, reduce ramp-up time and increase the number of posts. It is also a good practice to Rule sets to repositories – you don’t want everyone just pushing to the main branch!
Don’t forget that when building outdoors, everything you do is public. That means you have access to an incredible knowledge pool from a diverse community full of great ideas. Take advantage of it! And when people contribute, you get historical context as to why things were done a certain way. The caveat to making everything public is that you need to make sure you’re OK with someone seeing your work.
2. Configure for everyone
Once completed, this particular dashboard needed to be usable by non-technical people, which meant we needed to configure it in a simple and straightforward way. To ensure this, we built it in such a way that the project could be forked, allowing users to edit a single file in YAML and run the project from there. This single file controls the configuration for the frontend and backend in the root directory, so anyone can fork the project and make changes and have it work. The added benefit of building it this way was that we could make future changes upstream and they could commit them without merge conflicts, so they never had to click the “resolve conflicts” button.
Configuration is difficult and it is important to find something that fits well with your project and works for all users.
3. Introduce appropriate community branding
Because open source is focused on its community, what that community thinks of you and your project is important. To maintain a positive brand image, it’s important to be proactive with issues and code requests. Respond to people who have questions about your project, because they’re the ones who will use it! Posting issues frequently also helps show that your project is active and responsive.
Including appropriate community help files such as READMEthat tells people what the project is about, how they can contribute, and what else someone new to the project needs to know. Additional documentation such as a Code of Conduct, Security policyAnd Support Resources will also contribute to the health and branding of your project.
Shipping your project doesn’t mean you’re done—now it’s time to talk about it! Share the incredible work you’ve done by creating blog posts like this one, speaking at conferences, and showing demos to help nurture the community you’ve worked so hard to build.
What happens next?
The great thing about creating an open source metrics dashboard is that it helps us see what is working and what future improvements we can already plan for. Next, we want to:
- Add database support.
- Further customize what data we collect and what we display.
- Iterate the user interface.
- Unlock new data to identify trends over time.
- Check all dependencies and components of the project.
What’s next for you?
This was an incredible opportunity for us to use our skills to give back to an organization that contributes to open source and has a positive global impact. If you are interested in doing something similar, you can check out similar opportunities available on Forever – First Edition and help us work towards a better future!
Do you have ideas for further improvements or would you like to contribute to this project? Check it out here!
Written by
[ad_2]
Source link