From d52927125bba75ed42b00770c58672ecc2f89966 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Tue, 27 Feb 2024 13:58:45 +0100 Subject: [PATCH] chore: Improve contrib docs, add template workflows (#260) * chore: Improve contrib docs, add template workflows * Update CONTRIBUTING.md Co-authored-by: Vadim Makeev --------- Co-authored-by: Vadim Makeev --- .github/CODEOWNERS | 9 ++++ .github/ISSUE_TEMPLATE/bug.yml | 36 ++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 8 ++++ .github/workflows/codeql.yml | 41 ++++++++++++++++++ .github/workflows/pr-merge-conflicts.yml | 14 ++++++ CONTRIBUTING.md | 55 ++++++++++++++++++++++++ README.md | 23 +++++++++- 7 files changed, 185 insertions(+), 1 deletion(-) create mode 100644 .github/CODEOWNERS create mode 100644 .github/ISSUE_TEMPLATE/bug.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/workflows/codeql.yml create mode 100644 .github/workflows/pr-merge-conflicts.yml create mode 100644 CONTRIBUTING.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..f1b0b94 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,9 @@ +# This file is used to request PR reviews from the appropriate team. +# +# Order is important; the last matching pattern takes precedence. +# Each rule is more specific than the previous rules. +# For more information, see: +# https://docs.github.com/en/free-pro-team@latest/github/creating-cloning-and-archiving-repositories/about-code-owners + +# Default +* @mdn/core-yari-content diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml new file mode 100644 index 0000000..091d81b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -0,0 +1,36 @@ +name: "Issue report" +description: Report an unexpected problem or unintended behavior. +labels: ["needs triage"] +body: + - type: markdown + attributes: + value: | + ### Before you start + + **Want to fix the problem yourself?** This project is open source and we welcome fixes and improvements from the community! + + ↩ Check the project [CONTRIBUTING.md](../blob/main/CONTRIBUTING.md) guide to see how to get started. + + --- + - type: textarea + id: problem + attributes: + label: What information was incorrect, unhelpful, or incomplete? + validations: + required: true + - type: textarea + id: expected + attributes: + label: What did you expect to see? + validations: + required: true + - type: textarea + id: references + attributes: + label: Do you have any supporting links, references, or citations? + description: Link to information that helps us confirm your issue. + - type: textarea + id: more-info + attributes: + label: Do you have anything more you want to share? + description: For example, steps to reproduce, screenshots, screen recordings, or sample code. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..739d3cc --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Content or feature request + url: https://github.com/mdn/mdn/issues/new/choose + about: Propose new content for MDN Web Docs or submit a feature request using this link. + - name: MDN GitHub Discussions + url: https://github.com/orgs/mdn/discussions + about: Does your topic involve a lot of pages, or are you not sure how it can be split into actionable tasks? Consider starting a discussion first. diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml new file mode 100644 index 0000000..e8ca599 --- /dev/null +++ b/.github/workflows/codeql.yml @@ -0,0 +1,41 @@ +name: "CodeQL" + +on: + push: + branches: [main] + pull_request: + # The branches below must be a subset of the branches above + branches: [main] + +jobs: + analyze: + name: Analyze + runs-on: ubuntu-latest + if: github.repository == 'mdn/dom-examples' + permissions: + actions: read + contents: read + security-events: write + + strategy: + fail-fast: false + matrix: + language: ["javascript"] + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + # Initializes the CodeQL tools for scanning. + - name: Initialize CodeQL + uses: github/codeql-action/init@v3 + with: + languages: ${{ matrix.language }} + + # Autobuild attempts to build any compiled languages (C/C++, C#, or Java). + # If this step fails, then you should remove it and run the build manually (see below) + - name: Autobuild + uses: github/codeql-action/autobuild@v3 + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v3 diff --git a/.github/workflows/pr-merge-conflicts.yml b/.github/workflows/pr-merge-conflicts.yml new file mode 100644 index 0000000..bb59a8b --- /dev/null +++ b/.github/workflows/pr-merge-conflicts.yml @@ -0,0 +1,14 @@ +name: "Label PRs with conflicts" + +on: + push: + pull_request_target: + types: [synchronize] + +jobs: + label-merge-conflicts: + uses: mdn/workflows/.github/workflows/pr-rebase-needed.yml@main + with: + target-repo: "mdn/dom-examples" + secrets: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ef7ed6b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,55 @@ +# Contribution guide + +The "dom-examples" repository accompany various MDN DOM and Web API documentation pages on [MDN Web Docs](https://developer.mozilla.org). +This document will help you get started with contributions! + +## Types of contribution + +> [!NOTE] +> You can include an example directly in MDN pages using [`{{EmbedLiveSample()}}` macros](https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros/Commonly_used_macros#code_samples) or regular Markdown code blocks. +> These methods are simpler to maintain as the code lives beside the rest of the content. +> Only add examples to this repository if your example doesn't easily run on MDN pages for technical or security reasons. + +There are many ways you can help improve this repository! For example: + +- **Write a new example.** If you would like to add a new example, make sure this feature is supported by a stable version of modern browsers. +- **Improve an existing example.** You could make improvements or add some other changes which would make example more helpful to the users. +- **Fix a bug:** we have a list of [issues](https://github.com/mdn/dom-examples/issues), or maybe you found your own. + +## Getting started + +You will need to have Git and GitHub set up to be able to contribute. + +### Set up Git and GitHub + +For more information on setting up Git on your machine, [read this article](https://help.github.com/articles/set-up-git/). +With the above dependencies satisfied, [create your new account on GitHub](https://github.com/join). + +Next up, you need to fork and clone the repo to be able to contribute to it. +You can [learn about forking on GitHub](https://help.github.com/articles/fork-a-repo). +Once you have your own fork, [clone it to your local machine](https://help.github.com/articles/cloning-a-repository/). + +### Serving + +You should serve your example locally to see the results before submitting your changes. +There are a few different ways to do this depending on your preferred tooling methods. +See [Running a simple local HTTP server](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Tools_and_setup/set_up_a_local_testing_server#running_a_simple_local_http_server) for information on setting up a server. + +```bash +cd my-cool-example +python3 -m http.server +``` + +### Open a pull request + +Once you're satisfied, the final step is to [submit your pull request](https://help.github.com/articles/creating-a-pull-request/). +You can find more information about submitting pull requests in our [Community guidelines](https://developer.mozilla.org/en-US/docs/MDN/Community/Pull_requests) docs. + +### Including your example on MDN + +After your pull request is reviewed and merged, you can publish your example on MDN Web Docs. + +## Thank you + +Thanks a lot for your contribution! +If you'd like to ask questions or get in touch, feel free to drop by in [Discord](https://developer.mozilla.org/discord) or say hello in one of [our communication channels](https://developer.mozilla.org/en-US/docs/MDN/Community/Communication_channels). diff --git a/README.md b/README.md index 63c91f1..184c269 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,13 @@ Code examples that accompany various MDN DOM and Web API documentation pages. +> [!NOTE] +> You can include an example directly in MDN pages using [`{{EmbedLiveSample()}}` macros](https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros/Commonly_used_macros#code_samples) or regular Markdown code blocks. +> These methods are simpler to maintain as the code lives beside the rest of the content. +> Only add examples to this repository if your example doesn't easily run on MDN pages for technical or security reasons. + +## Repository contents + - The "abort-api" directory contains an example of how to use the "Abort API" (aka [AbortSignal](https://dom.spec.whatwg.org/#interface-AbortSignal) and [AbortController](https://dom.spec.whatwg.org/#interface-abortcontroller)). [Run the example live](https://mdn.github.io/dom-examples/abort-api/). - The "audiocontext-setsinkid" directory contains an example of how to use the [`AudioContext.setSinkId()`](https://developer.mozilla.org/docs/Web/API/AudioContext/setSinkId) method and related features. [Run the example live](https://mdn.github.io/dom-examples/audiocontext-setsinkid/). @@ -44,7 +51,7 @@ Code examples that accompany various MDN DOM and Web API documentation pages. - The "popover-api" directory is for examples and demos of the [Popover API](https://developer.mozilla.org/docs/Web/API/Popover_API) standard. Go to the [Popover API demo index](popover-api/) to see what's available. -- The "reporting-api" directory contains a couple of basic demos to show usage of the Reprting API. You can find more explanation of how the API works in the main MDN [Reporting API](https://developer.mozilla.org/docs/Web/API/Reporting_API) docs. [Run the deprecation report demo live](https://mdn.github.io/dom-examples/reporting-api/deprecation_report.html). +- The "reporting-api" directory contains a couple of basic demos to show usage of the Reporting API. You can find more explanation of how the API works in the main MDN [Reporting API](https://developer.mozilla.org/docs/Web/API/Reporting_API) docs. [Run the deprecation report demo live](https://mdn.github.io/dom-examples/reporting-api/deprecation_report.html). - The "resize-event" directory contains a basic demo to show how you can use the [resize event](https://developer.mozilla.org/docs/Web/API/Window/resize_event). Resize the browser window either by height or width to see the size of your current window. [Run the demo live](https://mdn.github.io/dom-examples/resize-event). @@ -79,3 +86,17 @@ Code examples that accompany various MDN DOM and Web API documentation pages. - The "webgpu-render-demo" directory contains an example that demonstrates basic usage of the [WebGPU API](https://developer.mozilla.org/docs/Web/API/WebGPU_API) render pipeline, which is used for rendering high-performance graphics via the GPU. [View the demo live](https://mdn.github.io/dom-examples/webgpu-render-demo/). - The "window-management-api" directory contains a basic demo to show usage of the [Window Management API](https://developer.mozilla.org/docs/Web/API/Window_Management_API). [View the demo live](https://mdn.github.io/dom-examples/window-management-api/). + +## Contribute to MDN Web Docs + +You can contribute to MDN Web Docs and be a part of our community through content contributions, engineering, or translation work. +The MDN Web Docs project welcomes contributions from everyone who shares our goals and wants to contribute constructively and respectfully within our community. + +To find out how to get started, see the [CONTRIBUTING.md](CONTRIBUTING.md) document in this repository. +By participating in and contributing to our projects and discussions, you acknowledge that you have read and agree to our [Code of Conduct](CODE_OF_CONDUCT.md). + +## Get in touch + +You can communicate with the MDN Web Docs team and community using the [communication channels][]. + +[communication channels]: https://developer.mozilla.org/en-US/docs/MDN/Community/Communication_channels