Skip to content

Commit

Permalink
chore: Improve contrib docs, add template workflows (#260)
Browse files Browse the repository at this point in the history
* chore: Improve contrib docs, add template workflows

* Update CONTRIBUTING.md

Co-authored-by: Vadim Makeev <[email protected]>

---------

Co-authored-by: Vadim Makeev <[email protected]>
  • Loading branch information
bsmth and pepelsbey authored Feb 27, 2024
1 parent 6c14a63 commit d529271
Show file tree
Hide file tree
Showing 7 changed files with 185 additions and 1 deletion.
9 changes: 9 additions & 0 deletions .github/CODEOWNERS
Validating CODEOWNERS rules …
Original file line number Diff line number Diff line change
@@ -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
36 changes: 36 additions & 0 deletions .github/ISSUE_TEMPLATE/bug.yml
Original file line number Diff line number Diff line change
@@ -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.
8 changes: 8 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -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.
41 changes: 41 additions & 0 deletions .github/workflows/codeql.yml
Original file line number Diff line number Diff line change
@@ -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
14 changes: 14 additions & 0 deletions .github/workflows/pr-merge-conflicts.yml
Original file line number Diff line number Diff line change
@@ -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 }}
55 changes: 55 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -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).
23 changes: 22 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/).
Expand Down Expand Up @@ -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).

Expand Down Expand Up @@ -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

0 comments on commit d529271

Please sign in to comment.