search

silverstripe / api.silverstripe.org

API documentation for the Silverstripe Framework
BSD 3-Clause "New" or "Revised" License
3 stars 14 forks source link

api.silverstripe.org only has core modules #104

Closed emteknetnz closed 1 year ago

emteknetnz commented 1 year ago

https://api.silverstripe.org/5/index.html

Only lists core (installer?) modules

It should list all supported modules (sink)

Means that heaps of api links in our changelogs for sink modules go nowhere e.g. CWP\CWP\Extensions\CwpSiteSummaryExtension (which is deprecated, though should still show in the 4 branch on api docs)

Stretch Goal

We mainly care about this for CMS5. If it's possible and easy to do it both for CMS4 and CMS5, do it. Otherwise, CMS5 is the priority.

PRs

Please take care to validate each of the branch mappings for each version! There are weird scenarios where it jumps a major release or where the same major release is available across multiple CMS versions. It is very likely I missed something.

andrewandante commented 1 year ago

👋 Gentlemen!

You should be able to "just" update https://github.com/silverstripe/api.silverstripe.org/blob/master/conf/doctum.json to bring in other modules. The version-mapping is the hardest bit to get right but it basically just means you need to match v1 of a module with v3 of CMS etc etc, its mostly straightforward

GuySartorelli commented 1 year ago

Thanks, that's good context. I'm probably going to refactor this though, so that we are grabbing the appropriate branches for supported modules based on https://github.com/silverstripe/supported-modules as a single source of truth.

GuySartorelli commented 1 year ago

@maxime-rainville @emteknetnz @sabina-talipova As discussed in standup, my current plan is to use https://github.com/silverstripe/supported-modules as a single source of truth here, so that each version references the correct branches of the correct modules. But I'll discuss our options here more broadly for discussion:

1. Keep the version mapping we currently have

This means having a map for each scenario where a branch name differs from the version being fetched - i.e. for scenarios where the branch names 3, 4, and 5 match those major releases, there is no map needed. For modules where the 1 branch is for CMS 4 and the 2 branch is for CMS 5, the existing "four-is-one" map is used.

There are some modules which were supported for CMS 4 but are not supported for CMS 5. I know that CMS 4 API docs is a "stretch goal" here but I'd strongly prefer that we don't have varying levels of correctness here.

For CMS 5 alone we have modules with the following branch numbers:

This doesn't take into account the branches for their CMS 3 or 4 compatible versions which also need to be included in the mapping. In some cases (e.g. fluent) the maps will be unique, so at the very least I'll be adding new code to handle a unique map instead of a shared one.

This also doesn't take into account the scenario where we may remove the CMS 4 'major' branches (e.g. 4 branch for silverstripe/framework), which we have discussed is an option. If we do that, the mapping becomes even more unique because we have different minor branch numbers for most modules.

2. Use the supported-modules repository as a source of truth

This means adding a "branches" key to denote which branches are supported for the given major release. This should be an array to handle scenarios like graphql where two separate branches are supported in CMS 4 - though only the more recent of the two will be used in the API docs for obvious reasons.

In this case there will be no esoteric "four-is-one" style mapping in this repository. It will simply fetch the list of supported modules for each major release and use the highest available branch name in the "branches" array.

This means whether we choose to remove the 4 branches or not, the workload for this module is the same. It's just pulling the branch listed in the supported modules repo.

This does mean we need to decide how to handle CMS 3 API docs. We should retain them in some form, so that the CMS 3 dev docs still link to somewhere. My recommendation would be to create a new 3 branch for the supported modules repository with the appropriate list of items.

Regardless of which option we choose

Decisions to make

  1. Should we pull CMS 4 API data from the 4 equivalent branch, or the 4.13 equivalent branch?
    • We can change our mind later - though it will be easier to do so if we use option 2 above.
  2. Should we continue to use version mapping in the dotum.json file in this repository, or should we pull data from the silverstripe/supported-modules repository?
emteknetnz commented 1 year ago

Makes sense to have supported modules as the source of truth, that I am worried that we'll need to be 4.13 in there which isn't good, we could very easily change to 4.14 in some instance and forget to update supported-modules

Ideally we should be able to on denote the major i.e. 4 in supported-modules, and the api fetcher is smart enough to know to pull from 4.13 if there's no 4 branch. This should be doable if the api fetch pulls from a github api /branches endpoint first to see what branches are there, then fetch the 4 branch if it's there, otherwise fetch from the highest minor branch, in this instance 4.13

GuySartorelli commented 1 year ago

That's a good shout. We should probably call it something other than "branches" in supported-modules if we're doing that, but that does sound pretty sensible. Assuming we're not likely to hit any rate limiting trying to do that for potentially every supported module.

maxime-rainville commented 1 year ago

I'm fine with using silverstripe/supported-modules as the "source of truth" for now. I'd be keen to come up with a more formal approach than "sticking a JSON file on github" at some point ... but that's another question for another card.

My preference would be to target the 4.13 branches. There could be some value in nuking the "next minor" branches for CMS 4 module to avoid getting changes targeted to branch that will never be release. Assuming that switching between the 4.13 and 4 branches is not difficult, I'm not overly fuss either way.

If keeping the CMS 3 APIs there require anything beyond very trivial changes, my instinct would be to nuke those.

GuySartorelli commented 1 year ago

Sweet.

With Steve's suggestion of looking at the 4 equivalent branches if they exist, and then querying github for the 4.13 equivalent branches as a fallback, I think that covers the desire to be able to nuke the "next minor" branches and also makes it robust for future major releases as well. So unless you want us to explicitly use the 4.13 equivalent branches, I'll go with that suggestion.

If keeping the CMS 3 APIs there require anything beyond very trivial changes, my instinct would be to nuke those.

The only change required will be to add a new 3 branch to the supported-modules repo with the relevant items, which will just be some very trivial monkey work of looking at the commit history to see what was supported for 3.

GuySartorelli commented 1 year ago

Merged into a new branch so we can validate this in UAT.

GuySartorelli commented 1 year ago

Cron isn't running (or isn't running the script that builds the docs site, at least) in UAT, which means I can't validate the code works. Opened a support ticket: https://servicedesk.silverstripe.cloud/support/tickets/106852

GuySartorelli commented 1 year ago

Works well in UAT, deployed to prod. Cron will run overnight, so I'm leaving this open until I can see it has worked as expected.

GuySartorelli commented 1 year ago

Prod now includes API from supported modules.