Skip to content

Latest commit

 

History

History
165 lines (106 loc) · 6.65 KB

CONTRIBUTING.md

File metadata and controls

165 lines (106 loc) · 6.65 KB
Raw

Contributions Welcome!

Interested in contributing? We'd love your help!

If you run into problems or find something confusing, please share it with us in this discussion. A great experience for new contributors is very important to us!

Please note that all activity on the snowpackjs/snowpack repository and our Discord is moderated and will be strictly enforced under Snowpack's Contributor Code of Conduct.

Our issue tracker is always organized with a selection of high-priority bugs, feature requests, and "help wanted!"/"good first issue" items. For general package troubleshooting and discussions, check out our Package Community discussion board.

Requirements

Snowpack uses yarn workspaces to manage multiple packages contained in this repository. To contribute, make sure that you have Yarn installed on your machine.

Initial setup

git clone https://github.com/withastro/snowpack.git
cd snowpack
yarn

Checking out and building a branch

git checkout some-branch-name
yarn # in case dependencies have changed
yarn build # re-builds all packages
# that's it! Your monorepo is set up and ready to run/test.

Build after changes

Some packages in the repo are written in JavaScript, and require no build step. Others (like Snowpack itself) are written in TypeScript, and require a build step to run.

# Option 1: A one-time build step
yarn build

# Option 2: Start a persistent TypeScript watcher, recompiling on every change
# Recommended for active development, when many changes are required
yarn build:watch

Updating and adding packages

Since this is a monorepo with several packages, if you want to update/add packages in the subrepos like create-snowpack-app/app-template-11ty you'll want to run the commands in the target subdirectory like

cd create-snowpack-app/app-template-vue
yarn add vue@latest

Tests

We recommend running all tests before you submit a PR. Tests will not work unless you have run a build yarn build.

Running tests

From the repository's root folder, run

yarn build
yarn test
yarn test:dev # sometimes flaky on windows, see #1171

Snapshot tests

Update March 2021: we’re working on improving this and would love your help converting old test directories to smaller TypeScript tests/fixtures!

All new tests should live in either test/snowpack, test/esinstall, or the test directory of one of our plugins (ex: plugins/plugin-dotenv/test/plugin.test.js). test/build is considered legacy and is in the process of getting converted into test/snowpack.

The way our snapshot tests work is they test Snowpack by building a project. Because Snowpack's build method uses the dev server internally, this is a good way to test the build behavior of both dev & build together.

You'll almost always have a "failed" snapshot test when you make a contribution because your new change will make the final build different. You'll want to take a new snapshot. To do this run:

yarn test -u

You'll notice this changes the snapshot file. Commit this change and submit it along with your PR.

Filtering tests

Jest supports basic test filtering to only run a subset of our test suite. The --testNamePattern flag also works as well.

yarn test treeshake

Run local snowpack in another project

You can run your local snowpack by path

yarn build
cd path/to/some-other-project
/path/to/snowpack-repository/snowpack/index.bin.js dev --verbose --reload

Or by linking the global snowpack library to your local clone

cd snowpack
npm link
cd path/to/some-other-project
snowpack dev --verbose --reload

To test a local version of the CLI tool use

node /path/to/snowpack-repository/create-snowpack-app/cli [my-new-dir] --template @snowpack/app-template-vue

To test a local version of the create-snowpack-app templates use

npx create-snowpack-app [my-new-dir] --template ./path/to/template

Note the path must start with must start with a . to be considered local

The --verbose flag enables additional logs which will help to identify the source of a problem. The --reload will clear the local cache which might have been created by a different snowpack version. Learn more about Snowpack's CLI flags.

Documentation

The Snowpack website source is located in /www. The documentation source files are located in /docs for contributor convenience.

The directories inside of /docs are automatically copied to /www/_template, so relative URLs in the documentation use /www as their base path.

Localization

If you’d like to help localize, we’d love your help! This is our proposed structure for /docs:

  • English translations in the root (e.g. /docs/tutorials/getting-started.md is English)
  • All other languages located in /docs/[ISO 639-1]/ folders, mirroring structure (e.g. /docs/tutorials/es/getting-started.md).

Some other considerations:

  • The .md filename should match its English name, only to mark it as the same document. Within the document itself, the title shown to users will be localized.
  • We’re open to having locale-specific guides that don’t exist in English, but please start a discussion before doing so, so we understand the context.

Pull Request Guidelines

Checkout a topic branch from a base branch, e.g. main, and merge back against that branch.

If adding a feature, it probably should have been brought up in a discussion instead before the PR was created.

Some tips for creating your first pull request:

  • Provide background for why a PR was created.
  • Link to any relevant issues, discussions, or past PRs.
  • Add accompanying tests if applicable.
  • Ensure all tests have been passed.
  • Be sure to add a changesets message along with your commit! Our friendly 🤖 bot will help guide you with more instructions.

Discussion

Join the Pika Discord