revise: clarifies language around the allowed number of sections in tasks and workflows

[claymcleod]

This pull request clarifies the allowed number of member sections within task and workflow blocks.

Rendered task and workflow sections.

It wasn't clear to me whether I should update bump the patch version number myself or whether the maintainers of the spec would bundle this change in with others—let me know if you'd like me to do that.

Closes #594.

Checklist

• Pull request details were added to CHANGELOG.md

[patmagee]

@jdidion For clarifications like this, should we make them against 1.1.2? or against 1.1?

[jdidion]

@claymcleod this is a great PR, thanks!

The only question is where to merge. Historically, our policy has been not to update a spec once it has been released. We recently modified this to allow patch releases, and have just released 1.1.1.

If we want to do another patch release to 1.1 (i.e., 1.1.2), then we should create a new branch for that (wdl-1.1.2), and this PR should target that branch. Otherwise, this PR should target wdl-1.2.

If it is decided that this branch should target wdl-1.2, then it will need to be updated to recognize the new requirements and hints section, as well as the deprecation of runtime.

In my opinion, we should get in the habit of making frequent patch releases (perhaps on a quarterly cadence, assuming there are any patches to make). So I suggest option 1 (targeting a new wdl-1.1.2 branch). Keep in mind that whenever a patch release is made, it is merged into the minor release branch, and then the next minor release branch will need to be rebased. In this case: merge wdl-1.1.2 into wdl-1.1, then rebase wdl-1.2 to wdl-1.1@HEAD.

Would appreciate feedback on this from others before going forward.

[geoffjentry]

+1 to 1.1.2

[claymcleod]

Yeah, I'm also in favor of 1.1.2.

[jdidion]

Moved to wdl-1.1.2

[jdidion]

Thanks @claymcleod. Overall I think this is great; however, I don't think we should be adding style recommendations here. Note that I haven't gone through the spec thoroughly to make sure I'm being consistent with this sentiment, but if there are places in the spec already where we're making stylistic recommendations I'd also advocate for moving those to a separate style guide.

[claymcleod]

@jdidion all comments have been addressed, the branch target has been updated to wdl-1.2, and, I believe at least, the changes necessary to make this merge-able into wdl-1.2 have been made. Please take a look and let me know if we need anything else.

[jdidion]

@claymcleod Regarding the target branch, maybe there was a misunderstanding. I think we agreed to target wdl-1.1.2. Can you please change it back?

Otherwise it looks good and I'm prepared to merge it.

[jdidion]

Made these changes here #632 rather than trying to rebase

[claymcleod]

Hey John,

Apologies, I was planning on responding last week but then was out.

In short, I had interpreted this comment:

If it is decided that this branch should target wdl-1.2, then it will need to be updated to recognize the new requirements and hints section, as well as the deprecation of runtime.

To mean that it would be okay to merge into 1.2 if I was willing to do the work to update the sections to be compliant with 1.2. Originally, I had agreed with that, but then I found some time to just update it for 1.2.

I'm okay with it going into either 1.1.2 or 1.2 provided that we make sure the right content gets on the right branch. In this case, the text you had merged in contains references to the requirements and hints sections while referring to the runtime section as 🗑️. Ultimately, the best course of action is up to you.