diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000000..d477d28388 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,19 @@ +### Requirements for Contributing Documentation + +Fill out the template below. Any pull request that does not include enough information to be reviewed in a timely manner may be closed at the maintainers' discretion. + +### Description of the Change + + + +### Testing Plan + + \ No newline at end of file diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 3d39e8326a..a98ddcb157 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,80 +1,132 @@ # Code of Conduct -## 1. Purpose +## Our Pledge -A primary goal of Next on Netlify Build Plugin is to be inclusive to the largest number of contributors, with the most varied and diverse backgrounds possible. As such, we are committed to providing a friendly, safe and welcoming environment for all, regardless of gender, sexual orientation, ability, ethnicity, socioeconomic status, and religion (or lack thereof). +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual identity +and orientation. -This code of conduct outlines our expectations for all those who participate in our community, as well as the consequences for unacceptable behavior. +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. -We invite all those who participate in Next on Netlify Build Plugin to help us create safe and positive experiences for everyone. +## Our Standards -## 2. Open Source Citizenship +Examples of behavior that contributes to a positive environment for our +community include: -A supplemental goal of this Code of Conduct is to increase open source citizenship by encouraging participants to recognize and strengthen the relationships between our actions and their effects on our community. +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community -Communities mirror the societies in which they exist and positive action is essential to counteract the many forms of inequality and abuses of power that exist in society. +Examples of unacceptable behavior include: -If you see someone who is making an extra effort to ensure our community is welcoming, friendly, and encourages all participants to contribute to the fullest extent, we want to know. +* The use of sexualized language or imagery, and sexual attention or + advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting -## 3. Expected Behavior +## Enforcement Responsibilities -The following behaviors are expected and requested of all community members: +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. -- Participate in an authentic and active way. In doing so, you contribute to the health and longevity of this community. -- Exercise consideration and respect in your speech and actions. -- Attempt collaboration before conflict. -- Refrain from demeaning, discriminatory, or harassing behavior and speech. -- Be mindful of your surroundings and of your fellow participants. Alert community leaders if you notice a dangerous situation, someone in distress, or violations of this Code of Conduct, even if they seem inconsequential. -- Remember that community event venues may be shared with members of the public; please be respectful to all patrons of these locations. +Community leaders 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, and will communicate reasons for moderation +decisions when appropriate. -## 4. Unacceptable Behavior +## Scope -The following behaviors are considered harassment and are unacceptable within our community: +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. -- Violence, threats of violence or violent language directed against another person. -- Sexist, racist, homophobic, transphobic, ableist or otherwise discriminatory jokes and language. -- Posting or displaying sexually explicit or violent material. -- Posting or threatening to post other people’s personally identifying information ("doxing"). -- Personal insults, particularly those related to gender, sexual orientation, race, religion, or disability. -- Inappropriate photography or recording. -- Inappropriate physical contact. You should have someone’s consent before touching them. -- Unwelcome sexual attention. This includes, sexualized comments or jokes; inappropriate touching, groping, and unwelcomed sexual advances. -- Deliberate intimidation, stalking or following (online or in person). -- Advocating for, or encouraging, any of the above behavior. -- Sustained disruption of community events, including talks and presentations. +## Enforcement -## 5. Consequences of Unacceptable Behavior +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +[INSERT CONTACT METHOD]. +All complaints will be reviewed and investigated promptly and fairly. -Unacceptable behavior from any community member, including sponsors and those with decision-making authority, will not be tolerated. +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. -Anyone asked to stop unacceptable behavior is expected to comply immediately. +## Enforcement Guidelines -If a community member engages in unacceptable behavior, the community organizers may take any action they deem appropriate, up to and including a temporary ban or permanent expulsion from the community without warning (and without refund in the case of a paid event). +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: -## 6. Reporting Guidelines +### 1. Correction -If you are subject to or witness unacceptable behavior, or have any other concerns, please notify a community organizer as soon as possible. devexperience@netlify.com +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. -Additionally, community organizers are available to help community members engage with local law enforcement or to otherwise help those experiencing unacceptable behavior feel safe. In the context of in-person events, organizers will also provide escorts as desired by the person experiencing distress. +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. -## 7. Addressing Grievances +### 2. Warning -If you feel you have been falsely or unfairly accused of violating this Code of Conduct, you should notify sdras with a concise description of your grievance. Your grievance will be handled in accordance with our existing governing policies. +**Community Impact**: A violation through a single incident or series +of actions. -## 8. Scope +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban. -We expect all community participants (contributors, paid or otherwise; sponsors; and other guests) to abide by this Code of Conduct in all community venues–online and in-person–as well as in all one-on-one communications pertaining to community business. +### 3. Temporary Ban -This code of conduct and its related procedures also applies to unacceptable behavior occurring outside the scope of community activities when such behavior has the potential to adversely affect the safety and well-being of community members. +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. -## 9. Contact info +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. -devexperience@netlify.com +### 4. Permanent Ban -## 10. License and attribution +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. -This Code of Conduct is distributed under a [Creative Commons Attribution-ShareAlike license](http://creativecommons.org/licenses/by-sa/3.0/). +**Consequence**: A permanent ban from any sort of public interaction within +the community. -Portions of text derived from the [Django Code of Conduct](https://www.djangoproject.com/conduct/) and the [Geek Feminism Anti-Harassment Policy](http://geekfeminism.wikia.com/wiki/Conference_anti-harassment/Policy). +## Attribution -Retrieved on October 26, 2020 from [http://citizencodeofconduct.org/](http://citizencodeofconduct.org/) +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.0, available at +[https://www.contributor-covenant.org/version/2/0/code_of_conduct.html][v2.0]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available +at [https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.0]: https://www.contributor-covenant.org/version/2/0/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0caef1cda9..38c241e2a5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,37 +1,136 @@ -# Contributions +# Contributing to Netlify Essential Plugins -🎉 Thanks for considering contributing to this project! 🎉 +👍🎉 First off, thanks for taking the time to contribute! 🎉👍 + +The following is a set of guidelines for contributing to Netlify and its packages, which are hosted in the Netlify Organization on GitHub. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request. + +Please note, we have a [code of conduct](CODE_OF_CONDUCT.md). Please follow it in all your interactions with this project. These guidelines will help you send a pull request. -If you're submitting an issue instead, please skip this document. +- [Code of Conduct](#code-of-conduct) +- [How Can I Contribute?](#how-can-i-contribute) + - [Reporting Bugs](#reporting-bugs) + - [Before Submitting A Bug Report](#before-submitting-a-bug-report) + - [How Do I Submit A (Good) Bug Report?](#how-do-i-submit-a-good-bug-report) + - [What is a reproducible test case?](#what-is-a-reproducible-test-case) + - [Why should you create a reproducible test case?](#why-should-you-create-a-reproducible-test-case) + - [Steps to create a reproducible test case](#steps-to-create-a-reproducible-test-case) + - [Benefits of reproducible test cases](#benefits-of-reproducible-test-cases) + - [Suggesting Enhancements](#suggesting-enhancements) + - [Before Submitting An Enhancement Suggestion](#before-submitting-an-enhancement-suggestion) + - [How Do I Submit A (Good) Enhancement Suggestion?](#how-do-i-submit-a-good-enhancement-suggestion) + - [Pull Requests](#pull-requests) +- [Styleguides](#styleguides) + - [Git Commit Messages](#git-commit-messages) + - [JavaScript Styleguide](#javascript-styleguide) + - [Documentation Styleguide](#documentation-styleguide) + +## Code of Conduct + +This project and everyone participating in it is governed by the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to the Netlify team. + +## How Can I Contribute? + +### Reporting Bugs + +This section guides you through submitting a bug report. Following these guidelines helps maintainers and the community understand your report :pencil:, reproduce the behavior :computer: :computer:, and find related reports :mag_right:. + +Before creating bug reports, please check [this list](#before-submitting-a-bug-report) as you might find out that you don't need to create one. When you are creating a bug report, please [include as many details as possible](#how-do-i-submit-a-good-bug-report). Fill out [the required template](https://github.com/netlify/netlify-plugin-nextjs/blob/main/.github/ISSUE_TEMPLATE/bug_report.md), the information it asks for helps us resolve issues faster. + +> **Note:** If you find a **Closed** issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one. + +#### Before Submitting A Bug Report + +* **Check the [forum](https://answers.netlify.com/)** for a list of common questions and problems related to this plugin. +* **Perform a [cursory search](https://github.com/netlify/netlify-plugin-nextjs/search?q=)** to see if the problem has already been reported. If it has **and the issue is still open**, add a comment to the existing issue instead of opening a new one. + +#### How Do I Submit A (Good) Bug Report? + +Bugs are tracked as [GitHub issues](https://guides.github.com/features/issues/). Create an issue and provide the following information by filling in [the template](https://github.com/netlify/netlify-plugin-nextjs/blob/main/.github/ISSUE_TEMPLATE/bug_report.md). + +Explain the problem and include a reproduction where possible, or additional details to help maintainers reproduce the problem. + +* **Use a clear and descriptive title** for the issue to identify the problem. +* **A link to a reproduction** where possible. [Follow these steps to produce a reproduction](#what-is-a-reproducible-test-case) +* **Describe the exact steps which reproduce the problem** in as many details as possible. When listing steps, **don't just say what you did, but explain how you did it**. +* **Provide specific examples to demonstrate the steps**. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you're providing snippets in the issue, use [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines). +* **Describe the behavior you observed after following the steps** and point out what exactly is the problem with that behavior. +* **Explain which behavior you expected to see instead and why.** +* **Include screenshots and animated GIFs** which show you following the described steps and clearly demonstrate the problem. You can use [this tool](https://www.cockos.com/licecap/) to record GIFs on macOS and Windows, and [this tool](https://github.com/colinkeenan/silentcast) or [this tool](https://github.com/GNOME/byzanz) on Linux. + +Provide more context by answering these questions: + +* **Did the problem start happening recently** (e.g. after updating to a new version) or was this always a problem? +* **Can you reliably reproduce the issue?** If not, provide details about how often the problem happens and under which conditions it normally happens. + +##### What is a reproducible test case? + +A reproducible test case is a small site built to demonstrate a problem - often this problem is caused by a bug in the plugin. Your reproducible test case should contain the bare minimum features needed to clearly demonstrate the bug. -If your pull request is related to a typo or the documentation being unclear, please click on the relevant page's `Edit` -button (pencil icon) and directly suggest a correction instead. +##### Why should you create a reproducible test case? -This project was made with ❤️. The simplest way to give back is by starring and sharing it online. +A reproducible test case lets you isolate the cause of a problem, which is the first step towards fixing it! -Everyone is welcome regardless of personal background. We enforce a [Code of conduct](CODE_OF_CONDUCT.md) in order to -promote a positive and inclusive environment. +The [most important part of any bug report](https://developer.mozilla.org/en-US/docs/Mozilla/QA/Bug_writing_guidelines#Writing_precise_steps_to_reproduce) is to describe the exact steps needed to reproduce the bug. -## Development process +A reproducible test case is a great way to share a specific environment that causes a bug. Your reproducible test case is the best way to help people that want to help _you_. -First fork and clone the repository. If you're not sure how to do this, please watch -[these videos](https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github). +##### Steps to create a reproducible test case -Run: +- Create a new site with a starter, like the Next.js +- Add our plugin and other plugins that are needed to demonstrate the problem. +- Add the code needed to recreate the error you've seen. +- Publish the code (your GitHub account is a good place to do this) and then link to it when creating an issue. -```bash -npm install -``` +##### Benefits of reproducible test cases -Make sure everything is correctly setup with: +- Smaller surface area: By removing everything but the error, you don't have to dig to find the bug. +- No need to publish secret code: You might not be able to publish your main site (for many reasons). Remaking a small part of it as a reproducible test case allows you to publicly demonstrate a problem without exposing any secret code. +- Proof of the bug: Sometimes a bug is caused by some combination of settings on your machine. A reproducible test case allows contributors to pull down your build and test it on their machines as well. This helps verify and narrow down the cause of a problem. +- Get help with fixing your bug: If someone else can reproduce your problem, they often have a good chance of fixing the problem. It's almost impossible to fix a bug without first being able to reproduce it. + +### Suggesting Enhancements -```bash -npm test -``` +This section guides you through submitting an enhancement suggestion, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion :pencil: and find related suggestions :mag_right:. -## How to write commit messages +Before creating enhancement suggestions, please check [this list](#before-submitting-an-enhancement-suggestion) as you might find out that you don't need to create one. When you are creating an enhancement suggestion, please [include as many details as possible](#how-do-i-submit-a-good-enhancement-suggestion). Fill in [the template](https://github.com/netlify/netlify-plugin-nextjs/blob/main/.github/ISSUE_TEMPLATE/feature_request.md), including the steps that you imagine you would take if the feature you're requesting existed. + +#### Before Submitting An Enhancement Suggestion + +* **Perform a [cursory search](https://github.com/netlify/netlify-plugin-nextjs/search?q=)** to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one. + +#### How Do I Submit A (Good) Enhancement Suggestion? + +Enhancement suggestions are tracked as [GitHub issues](https://guides.github.com/features/issues/). Create an issue and provide the following information: + +* **Use a clear and descriptive title** for the issue to identify the suggestion. +* **Provide a step-by-step description of the suggested enhancement** in as many details as possible. +* **Provide specific examples to demonstrate the steps**. Include copy/pasteable snippets which you use in those examples, as [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines). +* **Describe the current behavior** and **explain which behavior you expected to see instead** and why. +* **Include screenshots and animated GIFs** which help you demonstrate the steps or point out which feature the suggestion is related to. You can use [this tool](https://www.cockos.com/licecap/) to record GIFs on macOS and Windows, and [this tool](https://github.com/colinkeenan/silentcast) or [this tool](https://github.com/GNOME/byzanz) on Linux. +* **Explain why this enhancement would be useful** and why. + +### Pull Requests + +The process described here has several goals: + +- Maintain the project's quality +- Fix problems that are important to users +- Engage the community in working toward the best solutions possible +- Enable a sustainable system for the project's maintainers to review contributions + +Please follow these steps to have your contribution considered by the maintainers: + +1. Follow [the PR template](https://github.com/netlify/netlify-plugin-nextjs/blob/main/.github/PULL_REQUEST_TEMPLATE.md) +2. Follow the [styleguides](#styleguides) +3. After you submit your pull request, verify that all [status checks](https://help.github.com/articles/about-status-checks/) are passing
What if the status checks are failing?If a status check is failing, and you believe that the failure is unrelated to your change, please leave a comment on the pull request explaining why you believe the failure is unrelated. A maintainer will re-run the status check for you. If we conclude that the failure was a false positive, then we will open an issue to track that problem with our status check suite.
+ +While the prerequisites above must be satisfied prior to having your pull request reviewed, the reviewer(s) may ask you to complete additional design work, tests, or other changes before your pull request can be ultimately accepted. + +## Styleguides + +### Git Commit Messages We use [Conventional Commit messages](https://www.conventionalcommits.org/) to automate version management. @@ -41,7 +140,19 @@ Most common commit message prefixes are: * `feat:` which represents a new feature, and generate a minor release. * `feat!:`, `fix!:` or `refactor!:` and generate a major release. -## Releasing +For your commit message description consider these points: + +* Use the present tense ("Add feature" not "Added feature") +* Use the imperative mood ("Move cursor to..." not "Moves cursor to...") +* Limit the first line to 72 characters or less +* Reference issues and pull requests liberally after the first line + +### JavaScript Styleguide + +All JavaScript code is linted with [Prettier](https://prettier.io/). + +* Prefer the object spread operator (`{...anotherObj}`) to `Object.assign()` + +### Documentation Styleguide -1. Merge the release PR -2. Run `npm publish` +* Use [Markdown](https://github.github.com/gfm). diff --git a/README.md b/README.md index 2efe8b6c0e..e5dede95f6 100644 --- a/README.md +++ b/README.md @@ -66,7 +66,7 @@ yarn add @netlify/plugin-nextjs Read more about [file-based plugin installation](https://docs.netlify.com/configure-builds/build-plugins/#file-based-installation) in our docs. -## Docs +## Further Reading - [CLI Usage](https://github.com/netlify/netlify-plugin-nextjs/tree/main/docs/cli-usage.md) - [Custom Netlify Functions](https://github.com/netlify/netlify-plugin-nextjs/tree/main/docs/custom-functions.md) @@ -77,6 +77,22 @@ Read more about [file-based plugin installation](https://docs.netlify.com/config - [FAQ](https://github.com/netlify/netlify-plugin-nextjs/tree/main/docs/faq.md) - [Caveats](https://github.com/netlify/netlify-plugin-nextjs/tree/main/docs/caveats.md) +## Getting Help + +We'd love to hear from you! So, if you have any questions, comments, or bugs, let us know! You can either: + +- Open an issue on this repository +- Tweet us! We're [@netlify](https://twitter.com/Netlify) on Twitter +- Or, [join the community forums](https://answers.netlify.com) + +## Contributing + +We welcome contributions ❤️ - see the [CONTRIBUTING.md](CONTRIBUTING.md) file for details. + ## Credits This package extends the project [next-on-netlify](https://github.com/netlify/next-on-netlify), authored originally by [Finn Woelm](https://github.com/finnwoelm). + +## License + +This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.