Styx Emulator RFCs

The Styx Emulator project uses the RFC (request for comments) process for collaborating on substantial changes to Styx. RFCs enable contributors to collaborate during the design process, providing clarity and validation before jumping to implementation.

When the RFC process is necessary

The RFC process is necessary for changes which have a substantial impact on end users, operators, or contributors. "Substantial" is subjective, but it generally includes:

• Changes to core workflow functionality (pipelines, tasks, new concepts).
• Changes to how Styx is packaged, distributed, or configured.
• Changes with significant architectural implications (new runtimes, auth schemes, etc.).
• Changes which modify or introduce officially supported interfaces (HTTP APIs, external integrations, etc).

An RFC is not necessary for changes which have narrow scope and don't leave much to be discussed:

• Bug fixes and optimizations with no semantic change.
• Small features which only impact a narrow use case and affect users in an obvious way.

The RFC process aims to prevent wasted time and effort on substantial changes that end up being sent back to the drawing board. If your change takes minimal effort, or if you don't mind potentially scrapping it and starting over, feel free to skip this process. Do note however that pull requests may be closed with a polite request to submit an RFC.

Submitting an RFC

1. Fork this repository.

2. Copy the 000-example RFC template, naming it something like 000-my-proposal.

3. Write your proposal in 000-my-proposal/proposal.md.

   • Consult the Styx Conventions to guide your design.

   • Include any dependent assets (examples, screenshots) under your RFC directory.

4. Submit a pull request. The pull request number determines the RFC number.

   • Keep the description light; your proposal should contain all relevant information. Feel free to link to any relevant GitHub issues, since that helps with networking.

5. Rename the proposal directory to match the pull request number, e.g. 123-my-proposal.

   For convenience, update the PR description to link to the rendered proposal in the pull request body like so:

   [Rendered](https://github.com/{YOUR NAME}/rfcs/blob/{YOUR BRANCH}/123-my-proposal/proposal.md)
   

6. Feel free to review your own RFC and leave comments and questions as you reason about the problem and reach key decisions. Doing so helps build a public record of the decision-making process.

7. The RFC will be assigned to one of the Styx Maintainers. The assignee is responsible for providing feedback and eventually shepherding the RFC through the resolution process. Reach out to your RFC's assignee if you need any help with the RFC process.

8. Collect user feedback and votes (GitHub reactions) for your own RFC by linking to it in issues or contexts where it is relevant. Please be respectful of other RFC authors and avoid vote brigading; diversity of perspective is more important than having the most votes.

9. Amend your proposal in response to feedback by pushing more commits to your fork. Whenever possible, please make meaningful commits that summarize the changes and reasoning (rather than rebasing and force-pushing all the time).

Reviewing RFCs

Styx users and contributors are encouraged to review RFCs alongside the maintainers. Feedback from diverse perspectives is necessary for determining a proposal's efficacy, impact, and priority. Reviewing RFCs is also great practice for becoming a Maintainer someday!

Reviewers should focus on resolving open questions, surfacing risks and drawbacks, and providing constructive critique of the overall approach. The Styx Conventions serve as a guiding hand to determine the proposal's alignment with the Styx philosophy.

Reviewers should leave questions and comments on individual lines via PR review so that discussions may be threaded and marked as resolved. Leaving GitHub reactions also helps to measure consensus without cluttering the comment thread if you don't have much more to add.

Resolution

The review process should lead to consensus from two different perspectives:

• The maintainers have determined whether the proposal fits with the Styx design principles, whether the changes sufficiently improve the product and that the proposal is worth maintianing i.e. whether the benefits of the proposal outweigh any technical tradeoffs, or if it introduces an unsustainable maintenance burden.
• Enough community input has been provided to validate the need and efficacy of the proposal.

Once the review status stabilizes and clarity has been reached, the maintainer assignee will either:

• Merge the PR - there are no outstanding objections, and implementation can begin as soon as the RFC is merged.
• Close the PR - the proposal will be closed as the maintainers have determined that the proposal either doesn't fit within the Styx design principals or is unmaintainable
• Apply the S-postpone label: resolution will be deferred until a later time when the motivating factors may have changed.

Implementing an RFC

When an RFC is merged the maintainer assignee is responsible for opening an issue in the Styx Emulator repository to keep track of its implementation. The issue can be lightweight and just reference the RFC. The assignee must also add a link to the issue at the top of the RFC's proposal document.

An RFC author is not necessarily responsible for its implementation, though they may volunteer. If the maintainers have sufficient bandwidth they may place it on their roadmap by prioritizing the issue in a GitHub project. Otherwise the maintainers will add a S-Needs-Help label to the issue.

In any case, contributors may volunteer to implement a proposal provided that work has not already begun. If you would like to volunteer, please leave a comment on the issue to let others know!

From there, the implementation process falls under the normal Styx Emulator development process].

Revising an RFC

RFCs represent the planning phase. An RFC's proposal is not the source of truth for the feature's documentation, and should not be revised to keep up with later iterations after the initial proposal is implemented. A new RFC should be proposed for subsequent changes instead.

If an RFC is merged and later changes are deemed necessary prior to final (i.e. non-experimental) implementation, a follow-up PR may be submitted that updates the proposal in-place. In this case the RFC author must include a MAJOR.MINOR revision number in the proposal and maintain a brief summary of changes at the bottom of the proposal.

License

All RFCs, and any accompanying code and example content, will fall under the BSD-2 license present at the root of this repository.