RFC: Move documentation out of framework into a dedicated repo

[maxime-rainville]

Affected Version

4.11

Description

Having the documentation be part of framework is an historical artifact that provides no value and creates needless problems:

• It forces us to tag framework every release, even if nothing has changed
• It makes us run full builds of framework whenever we do doc changes, needlessly clogging our pipeline
• It pollutes the framework history with DOC changes unrelated to it.

Proposal

• Move the doc to a dedicated repo
• Update doc.silverstripe.org repo to track changes from the dedicated doc repo instead.
• Update the sink to include the dedicated repo in releases

Acceptance criteria

• Doc lives in a dedicated doc repo
• All doc is removed from framework
• Update the doc so the link to edit documentation points to the new repo
• Doc repo is added to kitchen sink (for release purposes)
• kitchen sink's cow.json is updated to put change log in new repo
• Update the doc.silverstripe.org Netlify generation logic to look for docs in the new repo
• Review framework PRs and call out the ones that might need to be updated so docs get put in the new repo, not in framework

Notes

• Does not include folding elemental doc back into main doc repo.
• If it's easy to do Show docs for latest stable release (not branch) doc.silverstripe.org#175 at the same time, do it.

PRs

• MNT Add readme for doc repo (4 branch) developer-docs#1
• MNT Add readme for doc repo (3 branch) developer-docs#2
• MNT Consume dev docs from the new developer-docs repo doc.silverstripe.org#243
• MNT Add action for building docs developer-docs#7
• DOC Update references for how to update documentation (4 branch) developer-docs#3
• DOC Update references for how to update documentation (3 branch) developer-docs#4
• MNT Move docs to new repository #10394
• MNT Add developer docs repo github-issue-search-client#99
• MNT Add developer docs to list of repos emteknetnz/silverstripe-data-fetcher#1
• MNT Add developer-docs for release purposes recipe-kitchen-sink#15

[emteknetnz]

+1

[michalkleiner]

👍

[christopherdarling]

👍

[maxime-rainville]

Got a bunch of core committers thumbing up and no one raising objections. I'll call this one accepted.

[GuySartorelli]

Currently the documentation in the website draws from the 4 branch which means it may include documentation for changes or features which haven't been given a stable release. Moving to a separate repository will give the additional benefit of being able to point to a stable-only copy of the docs.

Edit: See silverstripe/doc.silverstripe.org#175

[sminnee]

Sorry for the late response, but yeah this seems like a good idea - it make more sense to bundle the docs into the repo when we had fewer repos.

[gurucomkz]

Right... now instead of PR waiting years in one queue there will be 2 queues...

[GuySartorelli]

If you mean because there is a separation between a code PR in the framework module and the corresponding docs PR in the docs module, the same separation has always existed for code PRs in every module other than framework.

[GuySartorelli]

The following PRs have docs in them:

DOCS AND OTHER CHANGES

• NEW Adding constructor auto-DI for classes resolved through Injector #8564
• NEW Search across multiple searchable fields by default #10382
• NEW: Allow search field customisation #9341
• ENH Migrate away from deprecated Symfony cache classes #10187
• ENH Resolve relative paths in CSS files when combining #10134
• switch to standard X-Forwarded-Proto instead of X-Forwarded-Protocol #10018

DOCS ONLY

• DOCS SQLSelect::value() should be execute() #10280
• Clarify our process for managing security issue #10390
• DOCS: Document initialise graphql task #10218
• DOCS: custom graphql filter fields #10192
• DOCS GraphQL versioning draft mode #9867
• return ss3 example to docs #9866
• DOCS: Add release checklists #9253
• document new lazy loading feature #10361

I have added a comment to each indicating that the docs are moving, and so the PR will need to be updated/closed and a new PR created for the docs repo.

[GuySartorelli]

@emteknetnz Why is this assigned back to me? There are no outstanding questions or requested changes in the PRs?

[emteknetnz]

Oh right apologies, I thought that migrating the docs themselves hadn't been done, just checked and they have moved

[GuySartorelli]

New issue created to investigate why this isn't showing up in Elvis: silverstripe/github-issue-search-client#100

Closing this issue now as all actions are complete.