docs: new features in 3.6 #13739
docs: new features in 3.6 #13739
Conversation
Signed-off-by: Alan Clucas <alan@clucas.org>
Signed-off-by: Alan Clucas <alan@clucas.org>
|
I have also added the features merged since RC-2 |
Signed-off-by: Alan Clucas <alan@clucas.org>
Signed-off-by: Alan Clucas <alan@clucas.org>
| ## Build and Development | ||
|
|
||
| * [#13000](https://github.com/argoproj/argo-workflows/pull/13000): There is now a `/retest` command for retesting PRs in Github that occasionally fail in a flakey test | ||
| * [#12867](https://github.com/argoproj/argo-workflows/pull/12867): You can supply your own HTTP client when using the go API client, allowing for adding a proxy |
There was a problem hiding this comment.
The API client is an SDK change, so should be under an SDKs section
There was a problem hiding this comment.
SDK stands for software development kit, and this is under development. I don't think we need to split.
There was a problem hiding this comment.
"Build and Development", especially with the first item being a CI thing, makes it sound like items that are only relevant to Contributors, but the SDK is user facing. It's also called an "SDK" in the docs and in our own labels. Similarly, all contributor facing docs are under the "Developer Guide" in the docs.
I definitely don't think we should be creating new names for existing things, that's confusing at best.
SDK stands for software development kit, and this is under development
If you want to debate the difference between denotation and connotation: the connotations are not equivalent in this context, and if you were to use denotation, the entire codebase could be considered "development", so that is not a sufficient boundary
| ## Build and Development | ||
|
|
||
| * [#13000](https://github.com/argoproj/argo-workflows/pull/13000): There is now a `/retest` command for retesting PRs in Github that occasionally fail in a flakey test |
There was a problem hiding this comment.
dev stuff is not needed and is counter to the stated purpose of having a concise list (and there's plenty we could bikeshed about if we had a dev list)
There was a problem hiding this comment.
This is a new feature and this list is to enable people to discover new features. It isn't needed but I'd like to celebrate it by leaving it in.
There was a problem hiding this comment.
It's in the blog post already, and I think that's sufficient. The blog post includes "non-concise" things.
There are also certainly other new "CI features" if we wanted to call them that, which, as I wrote above, could definitely make for more bikeshedding
There was a problem hiding this comment.
It also is not specific to 3.6 either since it's CI; and that can also make for more bikeshedding
| @@ -237,6 +237,7 @@ nav: | |||
| - installation.md | |||
| - releases.md | |||
| - upgrading.md | |||
| - features-3.6.md | |||
There was a problem hiding this comment.
I don't think this should be a separate page per version as this will just keep increasing and eventually make it hard to see other pages in this section. It's also inconsistent with the upgrading guide and CHANGELOG, both of which are single pages (with CHANGELOG being eventually split into two per #13352). Deprecations from #13735 is also a single page. EDIT: See also #13735 (comment)
We previously discussed this together in the Oct 1st Contributor Meeting or earlier if I recall correctly, both before and after I met with CNCF Tech Writers
There was a problem hiding this comment.
We can drop new features-3.6.md from 3.7 because they'll be in 3.6's documentation. This is partially to enable automation of features-3.7.md too.
I can't find other projects that have a mega page full of new features for all prior versions, it seems normal to have one page per feature release.
There was a problem hiding this comment.
Most projects use the CHANGELOG, as we already do, or use the GH Releases page, both of which are not one page per release but one heading per release.
Internal consistency is more important in any case, and internally we do have headings per release already, as linked above.
We can drop new
features-3.6.mdfrom 3.7 because they'll be in 3.6's documentation
In that case, I would still have it as features.md so that the link /features remains the same for each version. Otherwise a user would have to duplicatively type release-3.6/features-3.6 and would be unable to use the version selector to see new features as release-3.7/features-3.6 (and so forth) would 404
There was a problem hiding this comment.
relative links to the docs for some of the features here would be really helpful to be able to see them in context when reading this
| * [#12441](https://github.com/argoproj/argo-workflows/pull/12441): Plugins can now be stopped, so that a stopped workflow will shutdown its plugin nodes | ||
| * The OSS artifact driver: |
There was a problem hiding this comment.
"Plugins" and "Artifacts" sections might be good to split out so it's not just "Controller". Artifacts and Plugins also run in the Server + Executor and Agent, respectively, so not in the Controller
There was a problem hiding this comment.
I've renamed it General. Most people don't care which component a feature happens in, it's an irrelevance to them.
There was a problem hiding this comment.
I don't think that's necessarily accurate -- if I use artifacts, having an "Artifacts" section would make it easy for me to see what's new with that "feature set".
Permissions are also relevant per component. But usage wise, it's less about the "architectural component" and more about the broader "feature set" (or "area" as we use in labels) like "Artifacts", "Plugins", "SSO", "SDKs", "CLI", etc, which is what I suggested above
Signed-off-by: Alan Clucas <alan@clucas.org>
Motivation
Keep users of Argo Workflows well informed of the new features in each release.
Until the next RC is out the feature list is subject to change. This is correct for RC-2 only. This PR will be updated as RC-3 is cut and merged then.
Modifications
Add a features-3.6.md (with the intention that each version will have its own page) with a concise list of all features based around the blog posting. Aiming for less celebratory, more factual.
Update the new features modal for the UI in preparation for 3.6 with a similar summary as per the Kubecon video.
Verification
Validated modal visually and by clicking the links. RTD 3.6 is not yet a thing, but changing to 3.5 for the cron-workflows link works as expected.
Validated new features page here in markdown too.