contributing.md

Contributing to PWABuilder

PWABuilder was founded by Microsoft as a community guided, open source project to help move PWA adoption forward. We want to make sure that as the project evolves, it remains simple to get started, maintain, and improve.

Many of the guidelines of this document are focused on promoting this sustainable simplicity.

Quick tech overview

PWABuilder is built with the following tech stack:

• https://nuxtjs.org/
• https://vuejs.org/
• https://www.typescriptlang.org/

It is helpful to be familiar with these technologies before contributing.

Get started developing

Prerequisites

At a minimum, you will need the following things properly installed on your computer to get started:

• Git
• Node.js (with NPM)
• NPM

To run e2e test coverage and build your changes (in production mode) you must also install:

• Java JDK
• Docker

Installation

• git clone <repository-url> this repository
• navigate inside the new directory
• npm install

Running in Development mode

• npm run dev
• visit your app at http://localhost:3000

Run tests on your (development mode) contributions

Running Unit Test Coverage

• npm test

Running e2e Test Coverage

• npm install selenium-standalone@latest -g only once
• selenium-standalone install only once
• npm run e2e

The Java JDK must be installed to perform these commands.

Run & build the production code

Production mode requires the same prerequisites and installation steps as development mode above.

However, production mode has a different build process outlined below:

• npm run build (builds and compiles the production code)

Docker must be installed to perform the above command.

• npm start (doesn't compile the code)

Frequently Asked Questions

Who can contribute?

Anyone who wants to be part of bringing PWAs to the web can contribute to PWABuilder! Skill level doesn't matter. All contributions big and small help us out. We have reviewers who can help you through the process the first few times.

Why does Microsoft need contributors?

PWABuilder was founded by Microsoft, but it's only moved forward because of the community's help. We open-sourced this because Microsoft wants to support the cross-platform development ecosystem and work with the community to direct the future of PWAs.

What kind of contributions is PWABuilder seeking?

No contribution is too small or too big. Bigger tasks take longer to review while smaller ones get feedback more quickly. Most contributors start with a small update, a bug fix, or docs improvement, and then move on to bigger tasks as they gain more familiarity with PWABuilder.

Where should I start contributing?

PWABuilder is split into multiple repositories. We recommend you get started with the following repos:

• https://github.com/pwa-builder/PWABuilder: This is the repo for the pwabuilder.com site. The master branch is the current public stable version. The redesign branch is where all new work is at the moment and will be merged to master when released.
• https://github.com/pwa-builder/PWABuilder-CLI: This is the repo for the PWABuilder CLI.
• https://github.com/pwa-builder/pwabuilder-api: This is the repo for the backend API used by PWABuilder. It is a node/express server and is currently deployed on Azure.
• https://github.com/pwa-builder/pwabuilder-serviceworkers: This is the repo for the service worker snippits used by the PWABuilder site.
• https://github.com/pwa-builder/pwabuilder-snippits: This is the repo for the features snippits used by the PWABuilder site.

What should I check before submitting a pull request?

For every contribution, you must:

• Test your code
• Target master branch (or an appropriate release branch if appropriate for a bug fix)
• Ensure that your contribution follows standard accessibility guidelines. Use tools like https://webhint.io/ to validate your changes.

If adding a new feature, you should open an issue with us on the main PWABuilder repo on Github (https://github.com/pwa-builder/PWABuilder) before you start coding.

Once you have opened your PR, feel free to add a reviewer (Github should recommend people on the team). When the PR has been reviewed and is good to go, a team member will merge it.

After my pull request gets merged, when does it become part of a PWABuilder release?

We will usually add fixes in the next planned release, but sometimes it makes sense to add a contribution in a later update to ensure the quality and performance of the next release.

Found bugs?

If you find a bug, you can help us by submitting an issue. Even better, you can submit a Pull Request with a fix.

Have other questions?

Please do not open issues for general support questions and keep our GitHub issues for bug reports and feature requests. There is a much better chance of getting your question answered on StackOverflow where questions should be tagged with pwabuilder

Special thanks

This contributing doc was inspired by our friends' version at the Windows Community Toolkit. thank you!