camunda
Make (breaking) changes to Connectors and element templates more obvious in the release notes
- Elevate breaking changes in w/ Connectors (and element templates) to release notes page
- Breaking changes should be part of the respective release notes page, however, the details should remain coupled with the respective split in SaaS vs. SM (brief statement on the release notes page, with a link to the source for more details)
- Explicitly clarify where older element templates will not support new features (and encourage updating)
- Make sure it's clear in the docs that older element templates are just that... old
From https://camunda.slack.com/archives/C02JLRNQQ05/p1718062703988039
@conceptualshark, getting this on your radar for a fresh perspective. Let me or the linked thread know if you have questions.
This should be part of https://github.com/camunda/engineering-leadership-team/issues/276 and the work @christinaausley is doing in this space, reassigning.
Elevate breaking changes in w/ Connectors (and element templates) to release notes page
Breaking changes and deprecations should go on the announcements page 👍 This includes explicitly clarifying where older element templates will not support new features (and encourage updating).
@conceptualshark Would you also expect to see the related SM content in the update guides?
@akeller Are there additional considerations for this issue in order to close it, or largely just keeping an eye out for these types of changes moving forward and ensuring they are included on the announcements page?
Great question @christinaausley, your clarification above makes a ton of sense. This is probably another good example to review for - do we need to retroactively adjust the announcements pages to uplevel this info (similar to the Keycloak example we were describing earlier today on Zoom)?
Cool 👍 When I backport I'll take a look at what is covered in each version and flag what may be missing collectively in a separate issue for all older versions, current, and next. I think making a PR for this batch of missing changes and starting from a clean slate is a good idea, rather than having to repeatedly go back and add things we missed one by one as they are flagged in the future.
I can ensure it is documented that breaking changes w/ Connectors and element templates are added to the announcements page moving forward and clarify where older element templates will not support new features (and encourage updating). @camunda/tech-writers will need to keep an eye out for when the connectors team updates the connector element template for a connector in a new version of C8.
@chriscampbell-camunda @alexcorremans Are you still seeing this come up frequently? If so, is it in a particular version of the docs?
@sbuettner Are there any instances for the upcoming alpha or minor, for example, where we will need to note something like this in the announcements?
Great timing, we just had a discussion about breaking changes with the Connectors team last week 🙂 Here is the incident channel.
@akeller Yes, we have this one. https://github.com/camunda/camunda-docs/pull/5137/files
@ztefanie Do you think it we should also we should add a note for people upgrading from 8.6.0 for example to 8.7? In addition to that we should also inform about the new option to encode the url which is also a change from 8.5.0
@akeller Yes, we have this one. https://github.com/camunda/camunda-docs/pull/5137/files
@ztefanie Do you think it we should also we should add a note for people upgrading from 8.6.0 for example to 8.7? In addition to that we should also inform about the new option to encode the url which is also a change from 8.5.0
Done here
@ztefanie @sbuettner It looks like we are caught up docs-wise on these types of updates, but what is the best way for me to follow or catch these changes? Is this a type of change we see every minor?
I added a note to the announcements/release notes Confluence page as a key change to look out for.
Semi-relates to https://github.com/camunda/camunda-docs/issues/5310.
This has not come up again and we do have somewhat of a resolution in place with the Confluence updates and announcements/release notes restructure. Closing.