From 73e450a66062bafb6dc4bf3a1fef24cc4803c319 Mon Sep 17 00:00:00 2001 From: Marvin Buss <34542414+marvinbuss@users.noreply.github.com> Date: Mon, 20 Dec 2021 09:06:12 +0100 Subject: [PATCH] New Issue/PR Templates & New Contributors Guide (#255) * New Issue/PR Templates & New Contributors Guide * updatd linting --- .github/ISSUE_TEMPLATE/BUG_REPORT.md | 20 --- .github/ISSUE_TEMPLATE/BUG_REPORT.yml | 66 +++++++++ .../ISSUE_TEMPLATE/DOCUMENTATION_ISSUE.yml | 33 +++++ .github/ISSUE_TEMPLATE/FEATURE_REQUEST.md | 12 -- .github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml | 42 ++++++ .github/ISSUE_TEMPLATE/config.yml | 7 +- .github/PULL_REQUEST_TEMPLATE.md | 18 ++- .github/linters/.textlintrc | 13 ++ CONTRIBUTING.md | 132 ++++++++++++++++++ README.md | 6 +- 10 files changed, 305 insertions(+), 44 deletions(-) delete mode 100644 .github/ISSUE_TEMPLATE/BUG_REPORT.md create mode 100644 .github/ISSUE_TEMPLATE/BUG_REPORT.yml create mode 100644 .github/ISSUE_TEMPLATE/DOCUMENTATION_ISSUE.yml delete mode 100644 .github/ISSUE_TEMPLATE/FEATURE_REQUEST.md create mode 100644 .github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml create mode 100644 .github/linters/.textlintrc create mode 100644 CONTRIBUTING.md diff --git a/.github/ISSUE_TEMPLATE/BUG_REPORT.md b/.github/ISSUE_TEMPLATE/BUG_REPORT.md deleted file mode 100644 index 63763107..00000000 --- a/.github/ISSUE_TEMPLATE/BUG_REPORT.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -name: "Bug report \U0001F41B" -about: Report errors or unexpected behaviour -title: 'Bug Report' -labels: bug -assignees: 'marvinbuss' ---- - - - - -**Describe the bug** - - -**Steps to reproduce** - -1. -2. - -**Screenshots** diff --git a/.github/ISSUE_TEMPLATE/BUG_REPORT.yml b/.github/ISSUE_TEMPLATE/BUG_REPORT.yml new file mode 100644 index 00000000..3137d015 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/BUG_REPORT.yml @@ -0,0 +1,66 @@ +name: "Bug report 🐛" +description: Report errors or unexpected behavior +title: "Bug: " +labels: + - bug + - backlog +assignees: "marvinbuss" + +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to fill out this report! Before submitting, please make sure to [search through existing issues](https://github.com/Azure/data-management-zone/issues) and [check the Known Issues section](/docs/DataManagementAnalytics-KnownIssues.md). + + - type: dropdown + id: deployment + attributes: + label: Deployment Mode + description: How was the deployment executed? + multiple: false + options: + - Deploy To Azure + - Azure DevOps + - GitHub Actions + validations: + required: true + + - type: textarea + id: reproduce + attributes: + label: Steps to reproduce + placeholder: Please share with us the step(s) required to reproduce the bug. + validations: + required: true + + - type: textarea + id: error + attributes: + label: Error Message + description: If possible, please share the error message that you received. + placeholder: Error Messages + render: json + validations: + required: false + + - type: textarea + id: screenshots + attributes: + label: Screenshots + description: If possible, please include screenshots and paste them into the markdown editor below. + placeholder: Screenshots + validations: + required: false + + - type: checkboxes + id: code_of_conduct + attributes: + label: Code of Conduct + description: The Code of Conduct helps create a safe space for everyone. We require that everyone must abide by it. + options: + - label: I agree to follow this project's [Code of Conduct](/CODE_OF_CONDUCT.md) + required: true + + - type: markdown + attributes: + value: "Thanks for completing this form!" diff --git a/.github/ISSUE_TEMPLATE/DOCUMENTATION_ISSUE.yml b/.github/ISSUE_TEMPLATE/DOCUMENTATION_ISSUE.yml new file mode 100644 index 00000000..22dccf67 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/DOCUMENTATION_ISSUE.yml @@ -0,0 +1,33 @@ +name: "Documentation Issue 📚" +description: Report issues in our documentation +title: "Documentation: " +labels: + - documentation + - backlog + +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to fill out this report! Before submitting, please make sure to [search through existing issues](https://github.com/Azure/data-management-zone/issues) and [check the Known Issues section](/docs/DataManagementAnalytics-KnownIssues.md). + + - type: textarea + id: description + attributes: + label: Documentation Issue + placeholder: Please share the name of the document along with supporting points on why it requires an amendment. + validations: + required: true + + - type: checkboxes + id: code_of_conduct + attributes: + label: Code of Conduct + description: The Code of Conduct helps create a safe space for everyone. We require that everyone must abide by it. + options: + - label: I agree to follow this project's [Code of Conduct](/CODE_OF_CONDUCT.md) + required: true + + - type: markdown + attributes: + value: "Thanks for completing this form!" diff --git a/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md b/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md deleted file mode 100644 index 4e13793a..00000000 --- a/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -name: "Feature request \U0001F680" -about: Suggest an idea for this project -title: 'Feature Request' -labels: feature -assignees: 'marvinbuss' ---- - - - - -**Describe the solution you'd like** diff --git a/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml b/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml new file mode 100644 index 00000000..ae81a613 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.yml @@ -0,0 +1,42 @@ +name: "Feature Request & Ideas 🚀" +description: Suggest a new feature or improvement (this does not mean you have to implement it) +title: "Feature: " +labels: + - feature + - backlog +assignees: "marvinbuss" + +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to fill out this report! Before submitting, please make sure to [search through existing issues](https://github.com/Azure/data-management-zone/issues) and [check the Known Issues section](/docs/DataManagementAnalytics-KnownIssues.md). + + - type: textarea + id: feature_description + attributes: + label: Feature or Idea - What? + placeholder: Briefly describe what the new feature, idea or enhancement entails. + validations: + required: true + + - type: textarea + id: feature_reason + attributes: + label: Feature or Idea - Why? + placeholder: Briefly describe why the new feature, idea or enhancement is required and what outcome you are trying to achieve. + validations: + required: true + + - type: checkboxes + id: code_of_conduct + attributes: + label: Code of Conduct + description: The Code of Conduct helps create a safe space for everyone. We require that everyone must abide by it. + options: + - label: I agree to follow this project's [Code of Conduct](/CODE_OF_CONDUCT.md) + required: true + + - type: markdown + attributes: + value: "Thanks for completing this form!" diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index a49eab2f..617544a9 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1 +1,6 @@ -blank_issues_enabled: true \ No newline at end of file +blank_issues_enabled: true + +contact_links: + - name: Microsoft Security Response Center 🔐 + url: https://msrc.microsoft.com/create-report + about: Please report security vulnerabilities here. \ No newline at end of file diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 353c11dc..28fbb9e8 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,7 +1,13 @@ - + +## Summary of the Pull Request -**This PR fixes** + +## References + + +## PR Checklist +* [ ] Closes Issue #xxx +* [ ] CLA signed. If not, go over [here](https://cla.opensource.microsoft.com/microsoft/Terminal) and sign the CLA + + +## Validation Steps Performed diff --git a/.github/linters/.textlintrc b/.github/linters/.textlintrc new file mode 100644 index 00000000..6c20b005 --- /dev/null +++ b/.github/linters/.textlintrc @@ -0,0 +1,13 @@ +{ + "filters": { + "comments": true + }, + "rules": { + "terminology": { + "defaultTerms": true, + "exclude": [ + "CLI tool(s)?" + ] + } + } +} \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..a47e6fb9 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,132 @@ +# Contributor's Guide + +This project welcomes community contributions in the form of [Issues](#issue-reports) and [Pull Requests](#pull-requests). Please note that by participating in this project, you agree to abide by the [Code of Conduct](/CODE_OF_CONDUCT.md) and the terms of the [CLA](#cla). + +> If you have a question, have discovered an issue or perhaps you would like to propose an enhancement or idea, please file an issue report **BEFORE** commencing work on it. + +## Contribution scope for Data Management & Analytics Scenario + +The following is the scope of contributions to this repository: + +As the Azure platform evolves and new services and features are validated in production with customers, the design guidelines will be updated in the overall architecture context. With new Services, Resources, Resource properties and API versions, the implementation guide and reference implementation must be updated as appropriate. + +## Issue Reports + +We are encouraging you to select between a [Bug Report](#bug-report), a [Feature Request](#feature-request), a [Documentation Issue](#documentation-issue) and a [Vulnerability Report](#vulnerability-report) when opening a new Issue in this repository. Please provide all the required information for the respective issue reports and make sure you accept the [Code of Conduct](/CODE_OF_CONDUCT.md). + +Before submitting a report, please search through the open and closed issues in this repository as well as through the [Known Issues](/docs/DataManagementAnalytics-KnownIssues.md). If a similar issue already exists, please upvote the existint issue comment(s) or leave a comment instead of opening a new issue. This helps us reduce the number issues and also simplifies the management on our side. Only if no existing item describes your issue report we encourage you to file a new one. + +### Bug Report + +Submit new bug reports using the "Bug Report" issue template. When submitting a bug report, please try to be as specific as possible by including a detailed description of how to reproduce the issue and also share any error messages or screenshots if possible. This will help us throubleshoot the bug/issue and apply fixes in a timely fashion. + +### Feature Request + +New feature requests and ideas must be submitted using the "Feature Request & Ideas" issue template. Please be specific about the "What?" and "Why?" by sharing what the feature entails and what the benefits of including this feature will be. + +### Documentation Issue + +Documentation issues should be submitted using the "Documentation Issue" issue template. Please be specific about which document needs to be updated and why. + +### Vulnerability Report + +Please read through the [security policy](/SECURITY.md) before submitting a vulnerability report. After reading through the guidelines, you can use the "Microsoft Security Response Center" to submit a new vulnerability. + +## Pull Requests + +We encourage users to not only submit issues but also start contributing to the repository by opening pull requests to fix issues that were submitted previously. Please always submit an issue before opening a pull request to make the team aware of the requested change and to be able to discuss the possible implications of proposed changes. Some issues or features may be quick and simple to describe and understand while others may require a detailed spec to agree on changes. + +### Getting Started + +Before starting to develop, you should fork this repository (see [this forking guide](https://guides.github.com/activities/forking/) for more information). Next, you should checkout the repository locally with `git clone git@github.com:{your_username}/{repo_name}.git`. + +### Tooling + +To help you contribute to the project more easily, you can find a [development container definition](/.devcontainer) in the `.devcontainer` folder of this repository. The development container has all the necessary tools and VS Code extensions enabled to provide you a curated development environment in which you can start developing without requiring you to install VS Code extensions on your local machine. Dev containers can be used via the [VS Code Remote - Containers](https://aka.ms/vscode-remote/download/containers) extension or [GitHub Codespaces](https://github.com/features/codespaces). + +If you would like to work inside your local environment, you should install the following tools locally: + +- PowerShell Core +- Azure CLI +- Git +- VS Code + +In addition, we recommend you to install the following VS Code extensions: + +- Azure Account +- Azure CLI Tools +- Azure Resource Manager (ARM) Tools +- Bicep +- PowerShell` + +### Development + +When working on the Infrastructure as Code (IaC) definitions in this repository, please be aware that you must always change the bicep code. The ARM templates, which you can also find i this repository, are just auto generated by building the Bicep definitions. + +Therefore, you should follow the following development cycle: + +1. Make changes to the Bicep code. +2. Build the new Bicep project by running `az bicep build -f main.bicep`. +3. Commit all files to your branch. +4. Submit your pull request. + +### Pull Request Information + +Before opening a pull request, ensure that an issue has been created to track the feature enhancement or bug that is being fixed. In the PR description, make sure you are linking the issue that this PR is about to close. To avoid multiple contributors working on the same issue, please add a comment to the issue that your are planning to work on. + +If the pull request is still work in progress, please open the pull request in draft mode. + +### Testing + +Testing is a key component in the development workflow. We run automated tests on all pull requests to enforce strict linting rules and also make sure that changes introduced to the IaC are not introducing code degredation. + +### Code Review + +If you want the team to review the changes, mark the pull request as "Ready for review". The team will get back to you and approve the PR, provide comments or request changes if necessary. The review process may take a few cycles in order to ensure that all content is of high quality and well structured. + +### Merge + +After the pull request has been reviewed and approved, the feature branch will be merged into the main branch and automatically closed and deleted. + +## Steering Committee and Stewardship of the project + +The Data Management & Analytics Scenario Committee and its members (aka Steering Committee Members) are the primary caretakers of the Data Management & Analytics Scenario repos including language, design, policy oversight, and reference implementations. Membership to steering committee will be solely baesd on active contribution and thought leadership in the preject and community. + +Voting members may be added once approved by the Steering Committee. All members abide by all organizational polices, including the code of conduct. The membership of a Steering Committee member can be withdrawn in the case of written notice of resignation or if the member is unreachable or unresponsive for more than three months. + +The following users are Steering Committee Members: + +| **NAME** | **GitHub Handle** | **Affiliated Organization** | +|:---------------------|:------------------|:----------------------------| +| Marvin Buss | @marvinbuss | Microsoft | +| Espen Brandt-Kjelsen | @esbran | Microsoft | +| Uday Pandya | @uday31in | Microsoft | +| Amanjeet Singh | @amanjeetsingh | Microsoft | +| Andre Hass | @andrehass | Microsoft | +| Roberto Cavalcanti | @rocavalc | Microsoft | +| Sanem Sever | @sasever | Microsoft | + +### Steering Committee Member Responsibilities + +Committee Members are responsible for reviewing and approving RFCs proposing new features or design changes. The initial Committee consists of Microsoft employees. It is expected that over time, community will grow and new community members will join Committee Members. Membership is heavily dependent on the level of contribution and expertise: individuals who contribute in meaningful ways to the project will be recognized accordingly. + +At any point in time, a Committee Member can nominate a strong community member to join the Steering Committee. Nominations should be submitted in the form of RFCs detailing why that individual is qualified and how they will contribute. After the RFC has been discussed, a unanimous vote will be required for the new Committee Member to be confirmed. + +## Community Colloboration + +Established community members are expected to demonstrate their adherence to the principles in this document, familiarity with project organization, roles, policies, procedures, conventions, etc., and technical and/or writing ability. Role-specific expectations, responsibilities, and requirements are enumerated below, adhereing the principle of Opensource contribution and governance: + +| Role | Responsibilities | Requirements | +| -----| ---------------- | ------------ | +| Member | Active contributor in the community | Sponsored by 2 reviewers and multiple contributions to the project | +| Reviewer | Review contributions from other members | History of review and authorship in the project | +| Approver | Contributions acceptance approval| Highly experienced active reviewer and contributor to the project | +| Steering Committee | Set direction and priorities for the project | Demonstrated responsibility and excellent technical judgement for the the project | + +## CLA + +This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit . + +When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repositories using our CLA. + +This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. \ No newline at end of file diff --git a/README.md b/README.md index bfd59349..9f46d48b 100644 --- a/README.md +++ b/README.md @@ -50,8 +50,4 @@ To deploy the Data Management Zone into your Azure Subscription, please follow t ## Contributing -This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit . - -When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repositories using our CLA. - -This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. +Please review the [Contributor's Guide](./CONTRIBUTING.md) for more information on how to contribute to this project via Issue Reports and Pull Requests.