Provide a PHP API for reasoning about modules, branches, and releases (…

…#28)

* NEW Make a unified JSON file for all CMS versions

* NEW Migrate logic from workflows for reasoning about repository metadata

.editorconfig

@@ -0,0 +1,16 @@
+# For more information about the properties used in
+# this file, please see the EditorConfig documentation:
+# http://editorconfig.org/
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 4
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false

.github/workflows/ci.yml

@@ -0,0 +1,11 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  ci:
+    name: CI
+    uses: silverstripe/gha-ci/.github/workflows/ci.yml@v1

.gitignore

@@ -0,0 +1,2 @@
+/vendor/
+composer.lock

README.md

@@ -1,37 +1,37 @@
 # 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.
 
-It's known to be used in the following repositories:
-
-- [silverstripe/cow](https://github.com/silverstripe/cow)
-- [silverstripe/tx-translator](https://github.com/silverstripe/silverstripe-tx-translator/)
-- [bringyourownideas/silverstripe-maintainence](https://github.com/bringyourownideas/silverstripe-maintenance)
-- [silverstripe/github-issue-search-client](https://github.com/silverstripe/github-issue-search-client)
-- [silverstripe/module-standardiser](https://github.com/silverstripe/module-standardiser)
+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>, though you're encouraged to use composer to pull in the data instead where appropriate.
 
 ## 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.
+- `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
 ```

composer.json

@@ -0,0 +1,17 @@
+{
+    "name": "silverstripe/supported-modules",
+    "description": "Metadata about Silverstripe CMS supported modules and other repositories maintained by Silverstripe",
+    "autoload": {
+        "psr-4": {
+            "SilverStripe\\SupportedModules\\": "src/",
+            "SilverStripe\\SupportedModules\\Tests\\": "tests/"
+        }
+    },
+    "require": {
+        "php": "^8.1",
+        "composer/semver": "^3.4"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^9.6"
+    }
+}