From bf1322da2d7cf667e926f44864a1debcea238732 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Charles-Edouard=20Br=C3=A9t=C3=A9ch=C3=A9?= Date: Wed, 6 Nov 2024 22:19:27 +0100 Subject: [PATCH] chore: add community to docs (#190) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Charles-Edouard Brétéché --- CODE_OF_CONDUCT.md | 74 +++++++++ website/docs/community/contribute.md | 150 ++++++++++++++++++ website/docs/community/index.md | 35 ++++ .../docs/community/making-a-pull-request.md | 111 +++++++++++++ website/docs/community/reporting-a-bug.md | 133 ++++++++++++++++ .../docs/community/reporting-a-docs-issue.md | 59 +++++++ website/docs/community/requesting-a-change.md | 106 +++++++++++++ website/mkdocs.yaml | 9 +- 8 files changed, 675 insertions(+), 2 deletions(-) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 website/docs/community/contribute.md create mode 100644 website/docs/community/index.md create mode 100644 website/docs/community/making-a-pull-request.md create mode 100644 website/docs/community/reporting-a-bug.md create mode 100644 website/docs/community/reporting-a-docs-issue.md create mode 100644 website/docs/community/requesting-a-change.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..88e1ae4 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,74 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for our community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or + advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, or to ban temporarily or permanently any +contributor for other behaviors that they deem inappropriate, threatening, +offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team privately at hello@squidfunk.com. The +project team will review and investigate all complaints, and will respond in a +way that it deems appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an +incident. Further details of specific enforcement policies may be posted +separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 1.4, available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ \ No newline at end of file diff --git a/website/docs/community/contribute.md b/website/docs/community/contribute.md new file mode 100644 index 0000000..6435495 --- /dev/null +++ b/website/docs/community/contribute.md @@ -0,0 +1,150 @@ +# Contributing + +Kyverno Envoy Plugin, developed by Kyverno, is an advanced end-to-end testing tool for Kubernetes. Our community plays a crucial role in shaping the project by reporting bugs, suggesting features, and improving documentation. + +We aim to make our issue tracker, discussion board, and documentation well-structured and easy to navigate. By following our guidelines, you can help us address your requests efficiently. + +## How you can contribute + +We appreciate your efforts in reporting bugs, requesting features, and engaging in discussions. Here's how you can contribute: + +### Creating an issue + +
+ +- :material-bug-outline:   + **Something is not working?** + + --- + + Report a bug by creating an issue with a reproduction + + --- + + [:octicons-arrow-right-24: Report a bug][report a bug] + +- :material-file-document-remove-outline:   + **Missing information in our docs?** + + --- + + Report missing information or potential inconsistencies in our documentation + + --- + + [:octicons-arrow-right-24: Report a docs issue][report a docs issue] + +- :material-lightbulb-on-20:   + **Want to submit an idea?** + + --- + + Propose a change, feature request, or suggest an improvement + + --- + + [:octicons-arrow-right-24: Request a change][request a change] + +- :material-account-question-outline:   + **Have a question or need help?** + + --- + + Ask a question on our [discussion board] and get in touch with our community + + --- + + [:octicons-arrow-right-24: Ask a question][discussion board] + +
+ +### Contributing + +
+ +- :material-source-pull:   + **Want to create a pull request?** + + --- + + Learn how to create a comprehensive and useful pull request (PR) + + --- + + [:octicons-arrow-right-24: Create a pull request][create a pull request] + +
+ + [report a bug]: reporting-a-bug.md + [report a docs issue]: reporting-a-docs-issue.md + [request a change]: requesting-a-change.md + [discussion board]: https://github.com/kyverno/kyverno-envoy-plugin/discussions + [issue tracker]: https://github.com/kyverno/kyverno-envoy-plugin/issues + [create a pull request]: making-a-pull-request.md + +## Checklist + +Before interacting within the project, please consider the following questions to ensure you're using the correct issue template and providing all necessary information. + +!!! warning "Issues, discussions, and comments are forever" + + Please note that everything you write is permanent and will remain for everyone to read – forever. Therefore, please always be nice and constructive, follow our contribution guidelines, and comply with our [Code of Conduct]. + +### Before creating an issue + +- Are you using the appropriate issue template, or is there another issue template that better fits the context of your request? +- Have you checked if a similar bug report or change request has already been created, or have you stumbled upon something that might be related? +- Did you fill out every field as requested and provide all additional information needed to comprehend your request? + +### Before asking a question + +- Is the topic a question for our [discussion board], or is it a bug report or change request that should be raised on our [issue tracker]? +- Is there an open discussion on the topic of your request? If the answer is yes, does your question match the direction of the discussion, or should you open a new discussion? +- Did you provide our community with all the necessary information to understand your question and help you quickly, or can you make it easier to help you? + +### Before commenting + +- Is your comment relevant to the topic of the current page, post, issue, or discussion, or is it better to create a new issue or discussion? +- Does your comment add value to the conversation? Is it constructive and respectful to our community and maintainers? Could you just use a [:octicons-smiley-16: reaction][reaction] instead? + + [Code of Conduct]: https://github.com/kyverno/kyverno-envoy-plugin/blob/main/CODE_OF_CONDUCT.md + [reaction]: https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/ + +## Rights and responsibilities + +As maintainers, we are entrusted with the responsibility to moderate communication within our community, including the authority to close, remove, reject, or edit issues, discussions, comments, commits, and to block users who do not align with our contribution guidelines and our [Code of Conduct]. This role requires us to be actively involved in maintaining the integrity and positive atmosphere of our community. Upholding these standards decisively ensures a respectful and inclusive environment for all members. + +### Code of Conduct + +Our [Code of Conduct] outlines the expectation for all community members to treat one another with respect, employing inclusive and welcoming language. Our commitment is to foster a positive and supportive environment, free of inappropriate, offensive, or harmful behavior. + +We take any violations seriously and will take appropriate action in response to uphold these values.[^1] + + [^1]: + **Warning and blocking policy:** + Given the increasing popularity of our project and our commitment to a healthy community, we've defined clear guidelines on how we proceed with violations: + + 1.1. **First warning:** Users displaying repeated inappropriate, offensive, or harmful behavior will receive a first warning. This warning serves as a formal notice that their behavior is not in alignment with our community standards and Code of Conduct. The first warning is permanent. + + 1.2. **Second warning and opportunity for resolution:** If the behavior persists, a second warning will be issued. Upon receiving the second warning, the user will be given a 5-day period for reflection, during which they are encouraged to publicly explain or apologize for their actions. This period is designed to offer an opportunity for openly clearing out any misunderstanding. + + 1.3. **Blocking:** Should there be no response or improvement in behavior following the second warning, we reserve the right to block the user from the community and repository. Blocking is considered a last resort, used only when absolutely necessary to protect the community's integrity and positive atmosphere. + + Blocking has been an exceptionally rare necessity in our overwhelmingly positive community, highlighting our preference for constructive dialogue and mutual respect. It aims to protect our community members and team. + +### Incomplete issues and duplicates + +We have invested significant time and effort in the setup of our contribution process, ensuring that we assess the essential requirements for reviewing and responding to issues effectively. Each field in our issue templates is thoughtfully designed to help us fully understand your concerns and the nature of your matter. We encourage all members to utilize the search function before submitting new issues or starting discussions to help avoid duplicates. Your cooperation is crucial in keeping our community's discussions constructive and organized. + + - **Mandatory completion of issue templates:** We need all of the information required in our issue templates because it ensures that every user and maintainer, regardless of their experience, can understand the content and severity of your bug report or change request. + + - **Closing incomplete issues:** + We *reserve the right to close issues lacking essential information*, such as but not limited to [minimal reproductions] or those not adhering to the quality standards and requirements specified in our issue templates. Such issues can be reopened once the missing information has been provided. + + - **Handling duplicates:** To maintain organized and efficient communication within our [issue tracker] and [discussion board], we *reserve the right to close any duplicated issues or lock duplicated discussions*. Opening multiple channels to ask the same question or report the same issue across different forums hinders our ability to manage and address community concerns effectively. This approach is vital for efficient time management, as duplicated questions can consume the time of multiple team members simultaneously. Ensuring that each issue or discussion is unique and progresses with new information helps us to maintain focus and support our community. + + We further *reserve the right to immediately close discussions or issues that are reopened without providing new information* or simply because users have not yet received a response to their issue/question, as the issue is marked as incomplete. + + - **Limitations of automated tools:** While we believe in the value and efficiency that automated tools bring to identifying potential issues (such as those identified by Lighthouse, Accessibility tools, and others), simply submitting an issue generated by these tools does not constitute a complete bug report. These tools sometimes produce verbose outputs and may include false positives, which necessitate a critical evaluation. You are of course welcome to attach generated reports to your issue. However, this does not substitute the requirement for a minimal reproduction or a thorough discussion of the findings. *We reserve the right to mark these issues as incomplete and close them.* This practice ensures that we are addressing genuine concerns with precision and clarity, rather than navigating through extensive automated outputs. + + diff --git a/website/docs/community/index.md b/website/docs/community/index.md new file mode 100644 index 0000000..7211dad --- /dev/null +++ b/website/docs/community/index.md @@ -0,0 +1,35 @@ +# Community + +The Kyverno Envoy Plugin has a growing community and we would definitely love to see you join and contribute. + +Everyone is welcome to make suggestions, report bugs, open feature requests, contribute code or docs, participate in discussions, write blogs or anything that can benefit the project. + +--- + +
+The Kyverno Envoy Plugin is built and maintained under the Kyverno umbrella but decisions are +

Community driven

+

Everyone's voice matters

+
+ +--- + +## Slack channel + +Join our slack channel [#kyverno](https://kubernetes.slack.com/archives/CLGR9BJU9) to meet with users, contributors and maintainers. + +## RoadMap + +For detailed information on our planned features and upcoming updates, please [view our Roadmap](https://github.com/kyverno/kyverno-envoy-plugin/blob/main/ROADMAP.md). + +## Contributing + +Please read the [contributing guide](https://github.com/kyverno/kyverno/blob/main/CONTRIBUTING.md) for details around: + +1. Code of Conduct +1. Code Culture +1. Details on how to contribute + +## Adopters + +If you are using the Kyverno Envoy Plugin and want to share it publicly we always appreciate a bit of support. Pull requests to the [ADOPTERS LIST](https://github.com/kyverno/kyverno-envoy-plugin/blob/main/ADOPTERS.md) will put a smile on our faces :smile: diff --git a/website/docs/community/making-a-pull-request.md b/website/docs/community/making-a-pull-request.md new file mode 100644 index 0000000..d906e6c --- /dev/null +++ b/website/docs/community/making-a-pull-request.md @@ -0,0 +1,111 @@ +# Pull Requests + +You can contribute by making a [pull request] that will be reviewed by maintainers and integrated into the main repository when the changes made are approved. You can contribute bug fixes, documentation changes, or new functionalities. + +[pull request]: https://docs.github.com/en/pull-requests + +!!! note "Considering a pull request" + + Before deciding to spend effort on making changes and creating a pull request, please discuss what you intend to do. If you are responding to what you think might be a bug, please issue a [bug report] first. If you intend to work on documentation, create a [documentation issue]. If you want to work on a new feature, please create a [change request]. + + Keep in mind the guidance given and let people advise you. It might be that there are easier solutions to the problem you perceive and want to address. It might be that what you want to achieve can already be done by configuration or [customization]. + +[bug report]: reporting-a-bug.md +[documentation issue]: reporting-a-docs-issue.md +[change request]: requesting-a-change.md + + +## Learning about pull requests + +Pull requests are a concept layered on top of Git by services that provide Git hosting. Before you consider making a pull request, you should familiarize yourself with the documentation on GitHub, the service we are using. The following articles are of particular importance: + +1. [Forking a repository] +2. [Creating a pull request from a fork] +3. [Creating a pull request] + +Note that they provide tailored documentation for different operating systems and different ways of interacting with GitHub. We do our best in the documentation here to describe the process as it applies but cannot cover all possible combinations of tools and ways of doing things. It is also important that you understand the concept of a pull-request in general before continuing. + +[Forking a repository]: https://docs.github.com/en/get-started/quickstart/fork-a-repo +[Creating a pull request from a fork]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork +[Creating a pull request]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request + +## Pull request process + +In the following, we describe the general process for making pull requests. The aim here is to provide the 30k ft overview before describing details later on. + +### Preparing changes and draft PR + +The diagram below describes what typically happens to repositories in the process or preparing a pull request. We will be discussing the review-revise process below. It is important that you understand the overall process first before you worry about specific commands. This is why we cover this first before providing instructions below. + +``` mermaid +sequenceDiagram + autonumber + + participant upstream + participant PR + participant fork + participant local + + upstream ->> fork: fork on GitHub + fork ->> local: clone to local + local ->> local: branch + loop prepare + loop push + loop edit + local ->> local: commit + end + local ->> fork: push + end + upstream ->> fork: merge in any changes + fork ->>+ PR: create draft PR + PR ->> PR: review your changes + end +``` + +1. Fork the Repository: Fork the upstream repository on GitHub to create your own copy. +2. Clone to Local: Clone your fork to your local machine. +3. Create a Branch: Create a topic branch for your changes. +4. Set Up Development Environment: Follow the instructions to set up a development environment. +5. Iterate and Commit: Make incremental changes and commit them with meaningful messages. +6. Push Regularly: Push your commits to your fork regularly. +7. Merge Changes from Upstream: Regularly merge changes from the original upstream repository to avoid conflicts. +8. Create a Draft Pull Request: Once satisfied with your changes, create a draft pull request for early feedback. +9. Review and Revise: Review your work critically, address feedback, and refine your changes. + +### Finalizing + +Once you are happy with your changes, you can move to the next step, finalizing +your pull request and asking for a more formal and detailed review. The diagram +below shows the process: + +``` mermaid +sequenceDiagram + autonumber + participant upstream + participant PR + participant fork + participant local + + activate PR + PR ->> PR: finalize PR + loop review + loop discuss + PR ->> PR: request review + PR ->> PR: discussion + local ->> fork: push further changes + end + PR ->> upstream: merge (and squash) + deactivate PR + fork ->> fork: delete branch + upstream ->> fork: pull + local ->> local: delete branch + fork ->> local: pull + end + +``` + +1. Finalize PR: Signal that your changes are ready for review. +2. Request Review: Ask the maintainer to review your changes. +3. Discuss and Revise: Engage in discussions, make necessary revisions, and iterate. +4. Merge and Squash: Once approved, the maintainer will merge and possibly squash your commits. +5. Clean Up: Delete the branch used for the PR from both your fork and local clone. \ No newline at end of file diff --git a/website/docs/community/reporting-a-bug.md b/website/docs/community/reporting-a-bug.md new file mode 100644 index 0000000..be2b8ab --- /dev/null +++ b/website/docs/community/reporting-a-bug.md @@ -0,0 +1,133 @@ +# Bug Reports + +If you think you have discovered a bug, you can help us by submitting an issue in our public [issue tracker], following this guide. + +[issue tracker]: https://github.com/kyverno/kyverno-envoy-plugin/issues + +## Before Creating an Issue + +With numerous users, issues are created regularly. The maintainers of this project strive to address bugs promptly. By following this guide, you will know exactly what information we need to help you quickly. + +__Please do the following before creating an issue:__ + +### Upgrade to Latest Version + +Chances are that the bug you discovered was already fixed in a subsequent version. Before reporting an issue, ensure that you're running the latest version. + +!!! warning "Bug fixes are not backported" + + Please understand that only bugs that occur in the latest version will be addressed. Also, to reduce duplicate efforts, fixes cannot always be backported to earlier versions. + +### Remove Customizations + +If you're using customizations like additional configurations, remove them before reporting a bug. We can't offer official support for bugs that might hide in your overrides, so make sure to omit custom settings from your configuration files. + +__Don't be shy to ask on our [discussion board] for help if you run into problems.__ + +[discussion board]: https://github.com/kyverno/kyverno-envoy-plugin/discussions + +### Search for Solutions + +At this stage, we know that the problem persists in the latest version and is not caused by any of your customizations. However, the problem might result from a small typo or a syntactical error in a configuration file. + +Before creating a bug report, save time for us and yourself by doing some research: + +1. [Search our documentation] for relevant sections related to your problem. Ensure everything is configured correctly. +2. [Search our issue tracker] as another user might have already reported the same problem. +3. [Search our discussion board] to see if other users are facing similar issues and find possible solutions. + +__Keep track of all search terms and relevant links; you'll need them in the bug report.__ + +[Search our documentation]: ?q= +[issue tracker]: https://github.com/kyverno/kyverno-envoy-plugin/issues +[discussion board]: https://github.com/kyverno/kyverno-envoy-plugin/discussions + +--- + +If you still haven't found a solution to your problem, create an issue. It's now likely that you've encountered something new. Read the following section to learn how to create a complete and helpful bug report. + +## Issue Template + +We have created a new issue template to make the bug reporting process as simple as possible and more efficient for our community and us. It consists of the following parts: + +- [Title] +- [Context] optional +- [Bug Description] +- [Related Links] +- [Reproduction] +- [Steps to Reproduce] +- [Browser] optional +- [Checklist] + +[Title]: #title +[Context]: #context +[Bug Description]: #bug-description +[Related Links]: #related-links +[Reproduction]: #reproduction +[Steps to Reproduce]: #steps-to-reproduce +[Browser]: #browser +[Checklist]: #checklist + +### Title + +A good title is short and descriptive. It should be a one-sentence executive summary of the issue, so the impact and severity of the bug can be inferred from the title. + +| | Example | +| -------- | -------- | +| :material-check:{ style="color: #4DB6AC" } __Clear__ | `apply` command fails with specific CRD +| :material-close:{ style="color: #EF5350" } __Wordy__ | The `apply` command fails when used with a certain Custom Resource Definition +| :material-close:{ style="color: #EF5350" } __Unclear__ | Command does not work +| :material-close:{ style="color: #EF5350" } __Useless__ | Help + +### Context optional {#context} + +Before describing the bug, you can provide additional context to help us understand what you were trying to achieve. Explain the circumstances under which the bug happens, and what you think might be relevant. Don't describe the bug here. + +### Bug Description + +Provide a clear, focused, specific, and concise summary of the bug you encountered. Explain why you think this is a bug that should be reported, and not to one of its dependencies. Follow these principles: + +- __Explain the what, not the how__ – don't explain how to reproduce the bug here, we're getting there. Focus on articulating the problem and its impact. +- __Keep it short and concise__ – if the bug can be precisely explained in one or two sentences, perfect. Don't inflate it. +- __One bug at a time__ – if you encounter several unrelated bugs, create separate issues for them. + +### Related Links + +Share links to relevant sections of our documentation and any related issues or discussions. This helps us improve our documentation and understand the problem better. + +### Reproduction + +A minimal reproduction is essential for a well-written bug report, as it allows us to recreate the conditions necessary to inspect the bug. Follow the guide to create a reproduction: + +[:material-bug: Create reproduction][Create reproduction]{ .md-button .md-button--primary } + +After creating the reproduction, you should have a `.zip` file, ideally not larger than 1 MB. Drag and drop the `.zip` file into the issue field, which will automatically upload it to GitHub. + +!!! warning "Don't share links to repositories" + + While linking to a repository is a common practice, we currently don't support this. The reproduction, created using the built-in info plugin, contains all necessary environment information. + + + +### Steps to Reproduce + +List specific steps to follow when running your reproduction to observe the bug. Keep the steps concise and ensure nothing is left out. Use simple language and focus on continuity. + +### Browser optional {#browser} + +If the bug only occurs in specific browsers, let us know which ones are affected. This field is optional, as it is only relevant for bugs that do not involve a crash when previewing or building your site. + +!!! incognito "Incognito Mode" + + Verify that the bug is not caused by a browser extension by switching to incognito mode. If the bug disappears, it is likely caused by an extension. + +### Checklist + +Before submitting, ensure you have: + +- Followed this guide thoroughly +- Provided all necessary information +- Created a minimal reproduction + +Thanks for following the guide and creating a high-quality bug report. We will take it from here. + diff --git a/website/docs/community/reporting-a-docs-issue.md b/website/docs/community/reporting-a-docs-issue.md new file mode 100644 index 0000000..bf1eab3 --- /dev/null +++ b/website/docs/community/reporting-a-docs-issue.md @@ -0,0 +1,59 @@ +# Documentation Issues + +The documentation includes extensive information on features, configurations, customizations, and more. If you have found an inconsistency or see room for improvement, please follow this guide to submit an issue on our [issue tracker]. + +[issue tracker]: https://github.com/kyverno/kyverno-envoy-plugin/issues + +## Issue Template + +Reporting a documentation issue is usually less involved than reporting a bug, as we don't need a [reproduction]. Please thoroughly read this guide before creating a new documentation issue, and provide the following information as part of the issue: + +- [Title] +- [Description] +- [Related Links] +- [Proposed Change] optional +- [Checklist] + + +[Title]: #title +[Description]: #description +[Related Links]: #related-links +[Proposed Change]: #proposed-change +[Checklist]: #checklist + +### Title + +A good title should be a short, one-sentence description of the issue, containing all relevant information and keywords to simplify the search in our issue tracker. + +| | Example | +| -------- | -------- | +| :material-check:{ style="color: #4DB6AC" } __Clear__ | Clarify resource templating setup +| :material-close:{ style="color: #EF5350" } __Unclear__ | Missing information in the docs +| :material-close:{ style="color: #EF5350" } __Useless__ | Help + +### Description + +Provide a clear and concise summary of the inconsistency or issue you encountered in the documentation or the documentation section that needs improvement. Explain why you think the documentation should be adjusted and describe the severity of the issue: + +- __Keep it short and concise__ – if the inconsistency or issue can be precisely explained in one or two sentences, perfect. Maintainers and future users will be grateful for having to read less. +- __One issue at a time__ – if you encounter several unrelated inconsistencies, please create separate issues for them. + +> __Why we need this__: describing the problem clearly and concisely is a prerequisite for improving our documentation – we need to understand what's wrong so we can fix it. + +### Related Links + +After you describe the documentation section that needs to be adjusted, share the link to this specific documentation section and other possibly related sections. Use anchor links (permanent links) where possible, as it simplifies discovery. + +> __Why we need this__: providing the links to the documentation helps us understand which sections of our documentation need to be adjusted, extended, or overhauled. + +### Proposed Change optional {#proposed-change} + +Now that you have provided us with the description and links to the documentation sections, you can help us, maintainers, and the community by proposing an improvement. You can sketch out rough ideas or write a concrete proposal. This field is optional but very helpful. + +> __Why we need this__: an improvement proposal can be beneficial for other users who encounter the same issue, as they offer solutions before we maintainers can update the documentation. + +### Checklist + +Thanks for following the guide and providing valuable feedback for our documentation – you are almost done. The checklist ensures that you have read this guide and have worked to your best knowledge to provide us with every piece of information we need to improve it. + +__We'll take it from here.__ diff --git a/website/docs/community/requesting-a-change.md b/website/docs/community/requesting-a-change.md new file mode 100644 index 0000000..62b8507 --- /dev/null +++ b/website/docs/community/requesting-a-change.md @@ -0,0 +1,106 @@ +# Change Requests + +We value every idea or contribution from our community. Please follow this guide before submitting your change request in our public [issue tracker]. This helps us better understand the proposed change and how it will benefit our community. + +[issue tracker]: https://github.com/kyverno/kyverno-envoy-plugin/issues + +## Before Creating an Issue + +Before you invest time in submitting a change request, answer these questions to determine if your idea is a good fit and matches the project's philosophy and tone. + +### It's Not a Bug, It's a Feature + +Change requests suggest minor adjustments, new features, or influence the project's direction. They are not intended for reporting bugs. Refer to our [bug reporting guide] for that. + +[bug reporting guide]: reporting-a-bug.md + +### Look for Sources of Inspiration + +If your idea is implemented in another tool or framework, collect information on its implementation. This helps us evaluate its fit more quickly. + +### Connect with Our Community + +Our [discussion board] is the best place to connect with our community. Seeking input from other users helps implement features that benefit a larger number of users. + +[discussion board]: https://github.com/kyverno/kyverno-envoy-plugin/discussions + +[:octicons-comment-discussion-16: Start a discussion][discussion board]{ .md-button .md-button--primary } + +## Issue Template + +After doing the preliminary work, create a change request. Follow these steps: + +- [Title] +- [Context] optional +- [Description] +- [Related Links] +- [Use Cases] +- [Visuals] optional +- [Checklist] + +[Title]: #title +[Context]: #context +[Description]: #description +[Related Links]: #related-links +[Use Cases]: #use-cases +[Visuals]: #visuals +[Checklist]: #checklist + +### Title + +A good title is short and descriptive, summarizing the idea so the potential impact and benefit can be inferred. + +| | Example | +| -------- | -------- | +| :material-check:{ style="color: #4DB6AC" } __Clear__ | Support for resource templating +| :material-close:{ style="color: #EF5350" } __Wordy__ | Add support for templating resources for easier testing +| :material-close:{ style="color: #EF5350" } __Unclear__ | Improve templating +| :material-close:{ style="color: #EF5350" } __Useless__ | Help + +### Context optional {#context} + +Provide additional context to help us understand what you are trying to achieve. Explain the circumstances and relevant settings without describing the change request itself. + +### Description + +Provide a detailed and clear description of your idea. Explain why your idea is relevant and should be implemented here, not in one of its dependencies. + +- __Explain the what, not the why__ – focus on describing the change request precisely. +- __Keep it short and concise__ – be brief and to the point. +- __One idea at a time__ – if you have multiple ideas, open separate change requests for each. + +### Related Links + +Provide any relevant links to issues, discussions, or documentation sections related to your change request. This helps us gain additional context. + +### Use Cases + +Explain how your change request would work from an author's and user's perspective. What is the expected impact, and why does it benefit other users? Would it potentially break existing functionality? + +### Visuals optional {#visuals} + +If you have any visuals, such as sketches, screenshots, mockups, or external assets, present them in this section. If you have seen this change used in other tools, showcase and describe its implementation. + +### Checklist + +Thanks for following the guide and creating a high-quality change request. The checklist ensures that you have read this guide and provided all necessary information for us to review your idea. + +__We'll take it from here.__ + +## Rejected Requests + +__Your change request got rejected? We're sorry for that.__ We understand it can be frustrating, but we always need to consider the needs of our entire community. If you're unsure why your change request was rejected, please ask for clarification. + +We consider the following principles when evaluating change requests: + +- [ ] Alignment with the project's vision and tone +- [ ] Compatibility with existing features and plugins +- [ ] Compatibility with all screen sizes and browsers +- [ ] Effort of implementation and maintenance +- [ ] Usefulness to the majority of users +- [ ] Simplicity and ease of use +- [ ] Accessibility + +If your idea was rejected, you can always implement it via [customization]. If you're unsure how or want to know if someone has already done it, get in touch with our community on the [discussion board]. + + diff --git a/website/mkdocs.yaml b/website/mkdocs.yaml index b6b5fa4..c9728cb 100644 --- a/website/mkdocs.yaml +++ b/website/mkdocs.yaml @@ -17,5 +17,10 @@ nav: - tutorials/istio.md - tutorials/mtls-istio.md - Performance: performance.md - - +- Community: + - community/index.md + - Contributing: community/contribute.md + - Reporting a bug: community/reporting-a-bug.md + - Reporting a docs issue: community/reporting-a-docs-issue.md + - Requesting a change: community/requesting-a-change.md + - Making a pull request: community/making-a-pull-request.md