NEW Make a unified JSON file for all CMS versions

README.md

@@ -1,11 +1,11 @@
 # Silverstripe CMS Supported Modules Metadata
 
-Used to generate the
-[supported modules list](https://www.silverstripe.org/software/addons/silverstripe-commercially-supported-module-list/) on silverstripe.org,
-and is the starting point for tooling such as
-our ["Elvis" bug tracker](https://github.com/silverstripe/github-issue-search-client).
+Metadata and some supporting PHP logic for determining which branches of various GitHub repositories relate to which versions of Silverstripe CMS.
 
-Each branch of this repository represents a major release line of Silverstripe CMS. You can fetch the JSON for the relevant release line by simply fetching the raw copy of `modules.json` for a given release branch, e.g. https://raw.githubusercontent.com/silverstripe/supported-modules/5/modules.json
+> [!IMPORTANT]
+> Only the main branch of this repository is maintained.
+
+You can fetch the JSON by simply fetching the raw copy of `repositories.json` file, e.g. <https://raw.githubusercontent.com/silverstripe/supported-modules/main/repositories.json>
 
 It's known to be used in the following repositories:
 
@@ -17,21 +17,29 @@ It's known to be used in the following repositories:
 
 ## Format
 
- * `github`: String. Github repository name (incl. org)
- * `gitlab`: String. Alternative gitlab repository name (incl. org)
- * `composer`: String. Packagist/composer name
- * `scrutinizer`: Boolean. Does this repo have Scrutinizer enabled?
- * `addons`: Boolean. Does this module exist on addons.silverstripe.org?
- * `type`: String. `supported-module` or `supported-dependency`
- * `githubId`: Number. The [id](https://docs.github.com/en/rest/reference/repos#get-a-repository) in Github. Used as a unique identifier.
- * `isCore`: Boolean. Is this considered a direct dependency of `silverstripe/installer`, `silverstripe/recipe-cms` or `silverstripe/recipe-core`?
- * `branches`: Array&lt;String&gt;. All major branches in lowest-to-heighest order (e.g. `["3", "4"]`, not `["4", "4.12"]`) of this module which are officially supported for this major release line of Silverstripe CMS. E.g. silverstripe/graphql was supported for `3` and `4` for the CMS 4 major release line.
-   * Systems using the branches array need to be smart enough to check for last-minor branches if the branch in the list is missing from github (e.g. if `4` is missing, fetch the list of branches for that repository from the github API and use the latest `4.x` (e.g. `4.13`) branch).
+There are several sections in the `repositories.json` file, denoting different categories of repositories:
+
+- `supportedModules`: Repositories representing supported modules. If cow cares about it, it should probably be in this category.
+- `workflow`: Repositories which hold GitHub actions and workflows. Note that this section omits the `packagist` key.
+- `tooling`: Repositories used to help streamline Silverstripe CMS maintenance
+- `misc`: All repositories we need to track which don't fit in one of the above categories.
+
+Each of the above sections holds an array of JSON objects with the following data:
+
+|key|type|description|
+|---|---|---|
+|`github`|_String_|Github repository name (incl. org)|
+|`packagist`|_String_|Packagist name. Only relevant if the repo isn't registered in packagist - otherwise null.|
+|`githubId`|_Number_|The [id](https://docs.github.com/en/rest/reference/repos#get-a-repository) in Github. Used as a unique identifier.|
+|`isCore`|_Boolean_|Is this considered a direct dependency of `silverstripe/installer`, `silverstripe/recipe-cms` or `silverstripe/recipe-core`? (Only relevant for supported modules)|
+|`lockstepped`|_Boolean_|Whether this is _always_ given a new minor release in "lock step" with Silverstripe CMS as a whole. (Only relevant for supported modules)|
+|`type`|_String_|One of "module", "recipe", "theme", or "other". (Only relevant for supported modules)|
+|`majorVersionMapping`|_Object_|A map of major versions, with the Silverstripe CMS major release lines as object keys and an array of all matching major release lines for the repository as values.<br>• The repository versions are branch names, but in most cases these will map to a major release line (e.g. "5" branch which represents the "5.x" release line)<br>• If a `"*"` key is present, it should be used for any CMS major release lines which do not have their own keys.<br>• If a CMS major release line is missing, and there is no `"*"` key, the repository should be ignored for that CMS major release line.<br>• If the value is an empty array, the default branch should be used.|
 
 ## Adding a repo
 
 You can easily retrieve the `githubId` via the following API call:
 
-```
+```text
 https://api.github.com/repos/my-org/my-repo
 ```