Establish process for adding new tools to the YAML directory. #17
Description
This page defines the approach to the development of a tooling repository and engagement strategy for the OpenAPI Initiative, specifically in how to add tools to the directory. It reflects:
- The statement of work defined in the OpenAPI Projects repository.
- The initial requirement to get the repository up-and-running.
This proposal will evolve over time as the initial cut of the repository is established and tools ingested.
Problem Statement
It’s a fact that any programming language - API specification-related or otherwise - is only as good as the tools that support it. Without relevant and workable tooling a community built around a given programming language will wither and die, as the users of the language - developers - do not have the affordances required to be productive human beings.
OpenAPI does not have a tooling problem in the sense there is no tooling - there is lots of it. However, easily finding the right and relevant tools can be a challenge and it is perceived that the OpenAPI Initiative could do more to help tooling makers publicize their wares. It’s not that the repositories don’t exist - there’s https://openapi.tools and https://apis.guru/awesome-openapi3/ - but these may be considered opinionated in their construct or coarse-grained in their data selection. There is also limited means to drive quality in the data, as they either work on snapshots based on automated searches or best efforts of maintainers with limited time available. The current mechanism of storing tools in the IMPLEMENTATIONS.md in the specification repository is also not fit-for-purpose, based on the number of pull requests that require merging.
The goal of the Tooling workstream is therefore to address by developing a dedicated repository for tooling that can become a ubiquitous community resource with the means to provide curated content.
To that end there are a number of specific objectives in its creation:
- Federate and merge existing repositories.
- Curate content.
- Publish centrally.
These objectives are expanded on below.
Federate and merge existing repositories
The first objective is to bring together the data that already exists in the community. It makes no sense to start from scratch given the considerable collateral that we already have from existing resources. The design approach is one of “loose-coupling”, where we can draw from existing repositories on an ongoing basis without affecting their presence or modus operandi.
The existing resources in scope are as follows (and already mentioned above):
- https://openapi.tools
- https://apis.guru/awesome-openapi3/
- IMPLEMENTATIONS.md
These will be combined into a single, attributed list in the Tooling repository and, in the case of https://openapi.tools continue to be merged into the near future. There are two significant advantages to this approach:
- Community: Repositories that are managed by active members of the OpenAPI community have buy-in from their contributors. We should facilitate continued use of the source repositories as “cutting them off” may alienate them from supporting the new Tooling repository.
- Wealth of knowledge: The repositories listed above hold significant collateral that can be drawn upon and curated to significantly seed the new Tooling repository. It will give us a significant head start.
The table below shows the in scope repositories for the first iteration:
| Repository | Approach | Rationale |
|---|---|---|
| https://openapi.tools | Merge | The repository has many active contributors and a good base set of metadata. We should continue to leverage the buy-in to this repository. The approach of federating has been discussed with Phil and as long there is attribution he is down with it (and it is supported by the underlying license). |
| https://apis.guru/awesome-openapi3/ | Migrate | Mike Ralphson has already discussed using this as the basis of an OpenAPI Initiative Tooling repository, as discussed in this paper. We should migrate the existing data/data captured mechanism (a GraphQL query on a given GitHub tag, Bayesian analysis of the readme of each repository) across to the Tooling repository and work with Mike to work out a future for the existing repository |
| IMPLEMENTATIONS.md | Migrate | The content of IMPLEMENTATIONS.md should be migrated across to the Tooling repository. This includes any outstanding pull requests - owners of those requests should be notified of the transition. |
The “Merge” approach for ingesting https://openapi.tools will be extensible, in that it will be future-proofed to allow us to bring other repositories and sources of information as we uncover them. This will allow us to always build on the existing community efforts, hopefully extending buy-in to our unified repository.
Analyze and curate content
The combined dataset will be housed in the new Tooling repository and be updated on a daily basis with changes from federated repositories using (most likely) GitHub actions as the build tool. Individual contributors will also be able to contribute to the repository where required (for example, where the tool is commercial and closed source).
The Bayesian analysis and GitHub metrics (Stars, etc.) will then be expanded to incorporate more metadata and extended across all repositories in an effort to ensure consistent categorization. This will help drive qualitative analysing of the data to ensure that anything that turns out irrelevant can be filtered (for example: tagged repositories with boilerplate code or limited community value, dead repositories, etc.)
Mopping up any failures in the automated analysis will be undertaken manually.
Publish centrally
The final objective - publishing the information for the use of the community - should be straightforward in terms of look-and-feel, i.e.:
- Inherit current OpenAPI theme.
- List of tooling in the style of https://openapi.tools.
However, this will be accompanied by filtering mechanisms that will make the most of metadata we can gather, viz.:
- Category.
- Open source vs commercial.
- GitHub metric (stars, etc.)
- Last update.
- License type.
The power of the new Tooling repository lies here: exploiting the available metadata to ensure our efforts enable the OpenAPI community to make informed decisions in their choice of tooling.