feat(rfc): Write RFC 004 to propose a grab bag of extensions #95

edwards-aws · 2025-10-24T16:42:53Z

Tracking Issue: #92

This is a request for comments about Collection of Small Improvements.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

rfcs/0004-enhanced-limits-and-capabilities.md

baxeaz · 2025-10-27T13:19:40Z

rfcs/0004-enhanced-limits-and-capabilities.md

+ 4. *cancelation* — If defined, provides details regarding how this action should be canceled. If not provided, then it is
+    treated as though provided with `<CancelationMethodTerminate>`.
+
+5. *python | bash | cmd | powershell | node* - Syntactic sugar for scripts,


I really like these

baxeaz · 2025-10-27T13:42:17Z

rfcs/0004-enhanced-limits-and-capabilities.md

+3. **Simplified Template Authoring**: Syntax sugar for common interpreters
+reduces boilerplate and makes templates more readable and maintainable.
+
+4. **Quicker Iteration**: Further parameterization allows for quicker iteration


At first read I didn't quite catch which of the changes fall under this - the parametrized action timeout and notifyPeriodInSeconds are described up top under "Enhanced format string support for" but being able to easily resubmit with parameter overrides for these is I think the real motivation?

Great, thanks! Maybe worth rephrasing in the summary to make that clearer?

epmog · 2025-10-28T21:22:53Z

rfcs/0004-enhanced-limits-and-capabilities.md

+ 1. Allowed characters: Any unicode character except those in the Cc unicode character category.
+ 2. Minimum length: 1 character.
+-3. Maximum length: 128 characters, after the format string has been resolved.
+3. Maximum length: 512 characters, after the format string has been resolved.


I don't think any of the other names follow the "after the format string has been resolved" wording even if it's true. Maybe we need to fix the spec to make it consistent wording (no behaviour change)?

rfcs/0004-enhanced-limits-and-capabilities.md

epmog · 2025-10-28T21:39:15Z

rfcs/0004-enhanced-limits-and-capabilities.md

+ 2. Must start with a letter or underscore character.
+ 3. Minimum length: 1 character
+-4. Maximum length: 64 character
+4. Maximum length: 512 character


nit: characters. Probably just an issue in the base spec

rfcs/0004-enhanced-limits-and-capabilities.md

epmog · 2025-10-28T21:49:50Z

rfcs/0004-enhanced-limits-and-capabilities.md

+   2. *bash* - Implicitly creates a Bash embedded file,
+   `command` becomes `bash`, and `args` get prefixed with the implicitly
+   generated file. The file extension is `.sh`.


Should it also be runnable? I guess only if it can be referenced outside this command.

I don't think we want it to be runnable. As it's implicitly run with bash, so there's no need for the executable permission to be set. It seems to me that making the file runnable is something that should be explicit? I could be off base there though.

epmog · 2025-10-28T21:51:34Z

rfcs/0004-enhanced-limits-and-capabilities.md

+   1. *python* - Implicitly creates a Python embedded file,
+   `command` becomes `python`, and `args` get prefixed with the implicitly
+   generated file. The file extension is `.py`.


Curious, do we need a way to refer to that embedded file elsewhere?

Seems that this sort of depends on if we want to be able to refer to the same embedded file in an environment OnEnter/OnExit, since currently there is only OnRun for task runs. Maybe there's an an implicit embedded file we can expose via the action or top-level name?

Otherwise that's a use-case where maybe we acknowledge that the syntactic sugar doesn't make sense.

See the conversation here #95 (comment)

I think that mostly addresses this.

jusiskin · 2025-10-31T16:19:28Z

rfcs/0004-enhanced-limits-and-capabilities.md

+   1. *python* - Implicitly creates a Python embedded file,
+   `command` becomes `python`, and `args` get prefixed with the implicitly


I'm wondering about an implementation detail specific to the python one. Some Linux distributions Python installs do not provide a python command on the PATH. They now only provide python3.

For example, on Ubuntu we see:

$ uname -a Linux ip-172-31-11-201 6.14.0-1011-aws #11~24.04.1-Ubuntu SMP Fri Aug 1 02:07:25 UTC 2025 x86_64 x86_64 x86_64 GNU/Linux $ python sh: 2: python: not found $ python3 Python 3.12.3 (main, Jun 18 2025, 17:59:45) [GCC 13.3.0] on linux Type "help", "copyright", "credits" or "license" for more information. >>>

We have a couple of options here:

Specify that OpenJD-compatible session implementations account for this (determine whether python/python3 is available, and use it)

Provide a python and python3 option here to let OpenJD template authors specify the command

Leave this as-is, but maybe expand in the spec that worker hosts have the python command available. We could maybe document that debian-based distros can use the python3-is-python package to achieve this.

There's also the converse issue, when there is python but not python3. I think it's important to nudge towards portable job templates, and solutions that avoid using a python3 command are better for portability.

I think we can keep it as is and add more clarification in the description that states something like

python (all lowercase) is expected to be a runnable command on a Worker host.

and similar for all other interpreters.

maybe that messaging adjusted with "available to the user running the command". It's definitely something folks can get tripped up on for PATH, aliases, etc. if they only modify their user and now who runs the command

Is it more "available in the runtime environment" compared to "available to the user"? The command could be provided by a step environment, a job environment, an externally defined environment, the user PATH configuration, or the system PATH configuration.

wiki/2023-09-Template-Schemas.md

mwiebe · 2025-12-16T04:30:56Z

rfcs/0004-enhanced-limits-and-capabilities.md

+```yaml
+steps:
+- name: RunPythonScript
+  script:


Would look nice to skip the 'actions' and 'onRun' nested objects when the only thing inside is a 'python' or other syntax sugar script. Do you think that's unambiguous/clear enough and doable in this rfc?

I think that would be nice, let me play around with the spec a bit to see how that would look in practice.

So I can think of a couple ideas.

actions: <StepActions> embeddedFiles: [ <EmbeddedFile>, ... ] # @optional python | bash | cmd | powershell | node: <DataString> # @optional @fmtstring[host] @incompatible command embeddedFiles @extension FEATURE_BUNDLE_1

in this you can optionally set the syntax sugar script at the <StepScript> level. If that is done you can't specify actions or embeddedFiles. Additionally you can't specify things like args, or timeouts. All defaults will be used.

This would be nice for quick, super simple scripts.

We create a new object called <SimpleAction> (let me know if you have a better name). This looks the exact same as an Action, but with all of the syntactic sugar included and no command.

actions: <StepActions> embeddedFiles: [ <EmbeddedFile>, ... ] # @optional python | bash | cmd | powershell | node: <SimpleAction> # @optional @fmtstring[host] @incompatible command embeddedFiles @extension FEATURE_BUNDLE_1

script: <DataString> # @fmtstring[host] args: [ <ArgString>, ... ] # @optional @fmtstring[host] timeout: <posinteger> # @optional timeout: <posinteger> | <posintstring> # @optional @fmtstring cancelation: <CancelationMethod> # @optional

This new object also gives us the option of using it for things like environment scripts.

Let me know what you think

I like the latter idea, that seems cleaner. If we want to apply it to the environment script case, the simple action would become onEnter and there would be no onExit, right? Similarly in the future if/when we add more actions than onRun to the step.

I think that makes sense.

Signed-off-by: Cody Edwards <[email protected]> added stuff again Signed-off-by: Cody Edwards <[email protected]> updated more stuff did more feat(rfc): Write RFC 004 to propose a grab bag of extensions Signed-off-by: Cody Edwards <[email protected]>

Signed-off-by: Cody Edwards <[email protected]>

edwards-aws · 2025-12-30T22:11:29Z

Please note #95 is now in final-comments - if there are any other concerns please let me know!

edwards-aws requested a review from a team as a code owner October 24, 2025 16:42

edwards-aws commented Oct 24, 2025

View reviewed changes

rfcs/0004-enhanced-limits-and-capabilities.md Show resolved Hide resolved

edwards-aws commented Oct 24, 2025

View reviewed changes

rfcs/0004-enhanced-limits-and-capabilities.md Outdated Show resolved Hide resolved

edwards-aws commented Oct 24, 2025

View reviewed changes

rfcs/0004-enhanced-limits-and-capabilities.md Outdated Show resolved Hide resolved

mwiebe requested changes Oct 27, 2025

View reviewed changes

baxeaz reviewed Oct 27, 2025

View reviewed changes

epmog reviewed Oct 28, 2025

View reviewed changes

jusiskin reviewed Nov 3, 2025

View reviewed changes

mwiebe reviewed Nov 5, 2025

View reviewed changes

wiki/2023-09-Template-Schemas.md Show resolved Hide resolved

mwiebe reviewed Nov 5, 2025

View reviewed changes

wiki/2023-09-Template-Schemas.md Outdated Show resolved Hide resolved

edwards-aws force-pushed the rfc4 branch from 4d187f5 to 023ccf3 Compare December 9, 2025 19:42

mwiebe reviewed Dec 16, 2025

View reviewed changes

edwards-aws added 4 commits December 29, 2025 16:42

address first round of comments

18abb4b

Signed-off-by: Cody Edwards <[email protected]>

add environment to list

508b27c

Signed-off-by: Cody Edwards <[email protected]>

move syntactic sugar

5dddd2f

Signed-off-by: Cody Edwards <[email protected]>

edwards-aws force-pushed the rfc4 branch from 023ccf3 to 5dddd2f Compare December 29, 2025 22:43

edwards-aws mentioned this pull request Dec 30, 2025

RFC: FEATURE_BUNDLE_1: Collection of Small Improvements #92

Open

7 tasks

mwiebe approved these changes Jan 9, 2026

View reviewed changes

Merge branch 'mainline' into rfc4

715afc5

edwards-aws merged commit 7929aeb into OpenJobDescription:mainline Jan 9, 2026
2 checks passed

		+ 1. python - Implicitly creates a Python embedded file,
		+ `command` becomes `python`, and `args` get prefixed with the implicitly

feat(rfc): Write RFC 004 to propose a grab bag of extensions #95

feat(rfc): Write RFC 004 to propose a grab bag of extensions #95

Uh oh!

Conversation

edwards-aws commented Oct 24, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

epmog Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

edwards-aws Nov 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

epmog Nov 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mwiebe Nov 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

edwards-aws Dec 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

edwards-aws commented Dec 30, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

epmog Oct 28, 2025 •

edited

Loading

edwards-aws Nov 3, 2025 •

edited

Loading

epmog Nov 3, 2025 •

edited

Loading

mwiebe Nov 4, 2025 •

edited

Loading

edwards-aws Dec 23, 2025 •

edited

Loading