search

silverstripe / developer-docs

Developer documentation for Silverstripe CMS
Other
6 stars 58 forks source link

DOC Document upgrading intervention/image #547

Closed GuySartorelli closed 1 week ago

GuySartorelli commented 2 weeks ago

Needs https://github.com/silverstripe/documentation-lint/pull/6 for linting to pass

Issue

GuySartorelli commented 1 week ago

I'm not sure why the changelog should be treated any differently.

The changelog is the one thing developers will look at when evaluating what changes they need to make, and it serves double duty as an upgrade guide. Giving all of the most important information in the changelog does two things:

  1. Reduces the number of extra pages developers need to look at to get the most relevant information
  2. Increases the chance that developers will actually see it - because lets face it a lot of devs will just not click on the links, but are fairly likely to copy/paste the code examples when we put them right in front of them.

I like the precedent that the important information is included in the changelog even if that same information is provided in other sections of the docs. I see the changelog as "here's all the most important information, including the most relevant info you need for upgrading", whereas the rest of the docs is for future reference or searching for specific information, outside of the context of releases.

GuySartorelli commented 1 week ago

I'm not keen to change that precedent now, especially when we don't have a team lead.

GuySartorelli commented 1 week ago

We've also got a while 'til this gets released, and if it's anything like CMS 5 we'll spend a fair amount of time going back over the changelog to decide what stays in there, so we can revisit this precedent then, if we haven't already revisited it for a minor release in the meantime (again, when we have a team lead preferably)