diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..651cd63 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,17 @@ +# https://EditorConfig.org + +# top-most EditorConfig file +root=true + +# Unix-style newlines with a newline ending every file +[*] +end_of_line = lf +insert_final_newline = true + +# 2 space indentation +indent_style = space +indent_size = 2 + +# Good practice +charset = utf-8 +trim_trailing_whitespace = true diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..dd5b58a --- /dev/null +++ b/.gitattributes @@ -0,0 +1,3 @@ +# Managing line ending conversions +# See http://git-scm.com/docs/gitattributes#_end-of-line_conversion +* text=auto eol=lf diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..b7175b0 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1 @@ +@test-kitchen/maintainers diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml new file mode 100644 index 0000000..83cd671 --- /dev/null +++ b/.github/workflows/lint.yml @@ -0,0 +1,41 @@ +--- +"on": + pull_request: + push: + branches: + - main + +concurrency: + group: lint-${{ github.ref }} + cancel-in-progress: true + +jobs: + yamllint: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v5 + - name: Run yaml Lint + uses: actionshub/yamllint@main + + markdown-lint: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v5 + + - name: Markdown lint + uses: DavidAnson/markdownlint-cli2-action@v20 + with: + globs: "**/*.md" + + markdown-link-check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v5 + - uses: tcort/github-action-markdown-link-check@v1 + with: + use-quiet-mode: "yes" + use-verbose-mode: "yes" + check-modified-files-only: "yes" + base-branch: "main" diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..678ed4b --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +.project +.DS_Store +.idea/ diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml new file mode 100644 index 0000000..ed65e9f --- /dev/null +++ b/.markdownlint-cli2.yaml @@ -0,0 +1,5 @@ +--- +config: + line-length: false # MD013 +ignores: + - .github/copilot-instructions.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..132685c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,14 @@ +# Release Process + +This release process applies to all Test Kitchen projects, but each project may have additional requirements. + +1. Perform a GitHub diff between main and the last released version. Determine whether included PRs justify a patch, minor or major version release. +2. Check out the main branch of the project being prepared for release. +3. Branch into a release-branch of the form `150_release_prep`. +4. Modify the `version.rb` file to specify the version for releasing. +5. Run `rake changelog` to regenerate the changelog. +6. `git commit` the `version.rb` and `CHANGELOG.md` changes to the branch and setup a PR for them. Allow the PR to run any automated tests and review the CHANGELOG for accuracy. +7. Merge the PR to main after review. +8. Switch your local copy to the main branch and `git pull` to pull in the release preparation changes. +9. Run `rake release` on the main branch. +10. Modify the `version.rb` file and bump the patch or minor version, and commit/push. diff --git a/README.md b/README.md index 1be366d..baeed5e 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,131 @@ -# rfcs -Request for Changes to github test-kitchen org repositories to track requests/decisions/and discussions +# Test-Kitchen Organization RFCs + +Many changes, including bug fixes and documentation improvements can be +implemented and reviewed via the normal GitHub pull request workflow. + +However, some changes are more substantial, and we ask that these be put +through a bit of a design process and produce a consensus in the community and +among the [maintainers]. + +The "RFC" (request for comments) process is intended to provide a consistent +and predictable path for new features and projects. + +[Active RFC List](https://github.com/test-kitchen/rfcs/pulls) + +## When you need to follow this process + +You need to follow this process if you intend to make "substantial" changes to +test-kitchen org repos that affect test-kitchen core, test-kitchen plugins, and +other test-kitchen org repos that would significantly impact how the product is +currently used or works and or their documentation. What constitutes a "substantial" +change is evolving based on community norms, but may include the following. + +- A new feature that creates new API, command, or option surface area. +- The removal of features that have already shipped in a minor release. +- The introduction of new idiomatic usage or conventions, even if they + do not include code changes. + +Some changes do not require an RFC: + +- Rephrasing, reorganizing, refactoring, or otherwise "changing shape does + not change meaning". +- Additions that strictly improve objective, numerical quality criteria + (warning removal, speedup, better platform coverage, more parallelism, trap + more errors, etc.) +- Addition or removal of warnings. +- Additions only likely to be noticed by other implementors, invisible to end + users. + +If you submit a pull request to implement a new feature without going through +the RFC process, it may be closed with a polite request to submit an RFC first. + +## Before creating an RFC + +It's often helpful to get feedback on your concept before diving into the level +of API design detail required for an RFC. **You may open an issue on this repo +to start a high-level discussion**, with the goal of eventually formulating an +RFC pull request with the specific implementation design. + +## What the process is + +In short, any major feature needs an RFC that has been merged into this RFC +repo as a markdown file. At that point the RFC is 'active' and may be +implemented with the goal of eventual inclusion into a test-kitchen org repository. + +- Fork [the RFC repo](https://github.com/test-kitchen/rfcs) (that's this one!) +- Copy `0000-template.md` to `rfcs/0000-my-feature.md` (Where 'my-feature' is + descriptive—don't assign an RFC number yet.) +- Fill in the RFC. Put care into the details: RFCs should include convincing + motivation, demonstrate understanding of the impact of the design, and be + clear about drawbacks or alternatives. +- Submit a pull request. As a pull request the RFC will receive design feedback + from the larger community, and the author should be prepared to revise it in + response. +- Build consensus and integrate feedback. RFCs that have broad support are much + more likely to make progress than those that don't receive any comments. +- RFCs rarely go through this process unchanged, especially as alternatives and + drawbacks are shown. You can make edits, big and small, to the RFC to clarify + or change the design, but make changes as new commits to the PR, and leave a + comment on the PR explaining your changes. Specifically, do not squash or + rebase commits after they are visible on the PR. +- RFCs that are candidates for inclusion will enter a "final comment period" + lasting 7 days. The beginning of this period will be signaled with a comment + and tag on the RFC's pull request. At that point, please post a link to the RFC + in the community chef slack [test-kitchen](https://chefcommunity.slack.com/archives/C2B6G1WCQ) + channel about the RFC to attract the community's attention. +- An RFC can be modified based upon feedback from the [maintainers] and + community. Significant modifications may trigger a new final comment period. +- An RFC may be rejected by the [maintainers] after public discussion has + settled and comments have been made summarizing the rationale for rejection. + A [maintainer] should then close the RFC's associated pull request. +- An RFC may be accepted at the close of its final comment period. A + [maintainer] will merge the RFC's associated pull request, at which point the + RFC will become 'active'. + +## The RFC life-cycle + +Once an RFC becomes active then authors may implement it and submit the feature +as a pull request to the test-kitchen repo affected. Being 'active' is not a rubber stamp, and +in particular still does not mean the feature will ultimately be merged; it +does mean that in principle all the major stakeholders have agreed to the +feature and are amenable to merging it. + +Furthermore, the fact that a given RFC has been accepted and is 'active' +implies nothing about what priority is assigned to its implementation, nor does +it imply anything about whether a test-kitchen developer has been assigned the task of +implementing the feature. While it is not necessary that the author of the RFC +also write the implementation, it is by far the most effective way to see an +RFC through to completion: authors should not expect that other project +developers will take on responsibility for implementing their accepted feature. + +Modifications to active RFC's can be done in follow-up PR's. We strive to write +each RFC in a manner that it will reflect the final design of the feature; but +the nature of the process means that we cannot expect every merged RFC to +actually reflect what the end result will be at the time of the next major +release. + +In general, once accepted, RFCs should not be substantially changed. Only very +minor changes should be submitted as amendments. More substantial changes +should be new RFCs, with a note added to the original RFC. + +## Implementing an RFC + +The author of an RFC is not obligated to implement it. Of course, the RFC +author (like any other developer) is welcome to post an implementation for +review after the RFC has been accepted. + +If you are interested in working on the implementation for an 'active' RFC, but +cannot determine if someone else is already working on it, feel free to ask +(e.g. by leaving a comment on the associated issue). + +## Reviewing RFC's + +The [maintainers] will review open RFC pull requests, giving feedback and +eventually accepting or rejecting each one. Every accepted feature should have +a maintainer champion, who will represent the feature and its progress. + +### Inspiration + +The test-kitchen RFC process is inspired by the [rubygems], RFC processes. + +[rubygems]: https://github.com/rubygems/rfcs diff --git a/rfcs/0000-template.md b/rfcs/0000-template.md new file mode 100644 index 0000000..4f17ed0 --- /dev/null +++ b/rfcs/0000-template.md @@ -0,0 +1,72 @@ +# Title + +--- + +| **RFC** | **Author** | **Status** | **Type** | **Replaces** | **Related Issue** | +|---------|------------|------------|----------|--------------|-------------------| +| 0000 | Alan Smithee | Draft | | RFC - [0000-template](https://github.com/test-kitchen/rfcs/blob/main/rfcs/0000-template.md) | [example_issue](https://github.com/test-kitchen/kitchen-dokken/issues/1) | + +--- + +## Summary + +Description and rationale. + +--- + +## Motivation + + As a <>, + I want to <>, + so that <>. + +--- + +## Proposal + +A detailed description of the planned implementation, which the RFC author agrees to execute. + +--- + +## Benefits + +Why is this a good idea? + +--- + +## Implementation Plan + +High level steps to implement this change. + +1. step 1 +2. step 2 +3. step 3 + +--- + +## Alternatives Considered + +What other options were considered and why were they not chosen? + +--- + +## Feedback Requested + +What feedback are you looking for? + +--- + +## Anticipated Downstream Impact + +Which other tools will be impacted by this work? + +--- + +## Copyright + +This work is in the public domain. In jurisdictions that do not allow for this, +this work is available under CC0. To the extent possible under law, the person +who associated CC0 with this work has waived all copyright and related or +neighboring rights to this work. + +---