172 lines
5.2 KiB
Raw Permalink Normal View History

2018-03-31 00:55:55 +00:00
# Contributing to Pinafore
## Installing
To install with dev dependencies, run:
## Dev server
2018-03-31 00:55:55 +00:00
To run a dev server with hot reloading:
yarn run dev
2018-03-31 00:55:55 +00:00
Now it's running at `localhost:4002`.
**Linux users:** for file changes to work,
you'll probably want to run `export CHOKIDAR_USEPOLLING=1`
because of [this issue](
2018-03-31 00:55:55 +00:00
## Linting
Pinafore uses [JavaScript Standard Style](
yarn run lint
2018-03-31 00:55:55 +00:00
Automatically fix most linting issues:
yarn run lint-fix
2018-03-31 00:55:55 +00:00
## Integration tests
Integration tests use [TestCafé]( and a live local Mastodon instance
running on `localhost:3000`.
### Running integration tests
2018-03-31 00:55:55 +00:00
The integration tests require running Mastodon itself,
meaning the [Mastodon development guide](
is relevant here. In particular, you'll need a recent
version of Ruby, Redis, and Postgres running. For a full list of deps, see `bin/`.
2018-04-12 16:44:02 +00:00
2018-03-31 00:55:55 +00:00
Run integration tests, using headless Chrome by default:
npm test
Run tests for a particular browser:
BROWSER=chrome yarn run test-browser
BROWSER=chrome:headless yarn run test-browser
BROWSER=firefox yarn run test-browser
BROWSER=firefox:headless yarn run test-browser
BROWSER=safari yarn run test-browser
BROWSER=edge yarn run test-browser
2018-03-31 00:55:55 +00:00
If the script isn't able to set up the Postgres database, try running:
sudo su - postgres
psql -d template1 -c "CREATE USER pinafore WITH PASSWORD 'pinafore' CREATEDB;"
### Testing in development mode
2018-03-31 00:55:55 +00:00
In separate terminals:
1\. Run a Mastodon dev server:
yarn run run-mastodon
2018-03-31 00:55:55 +00:00
2\. Run a Pinafore dev server:
yarn run dev
2018-03-31 00:55:55 +00:00
3\. Run a debuggable TestCafé instance:
npx testcafe --debug-mode chrome tests/spec
2018-03-31 00:55:55 +00:00
### Test conventions
2018-03-31 00:55:55 +00:00
The tests have a naming convention:
2018-04-12 03:33:34 +00:00
* `0xx-test-name.js`: tests that don't modify the Mastodon database (read-only)
* `1xx-test-name.js`: tests that do modify the Mastodon database (read-write)
2018-04-12 03:33:34 +00:00
In principle the `0-` tests don't have to worry about
2018-04-12 16:44:02 +00:00
clobbering each other, whereas the `1-` ones do.
### Mastodon used for testing
There are two parts to the Mastodon data used for testing:
1. A Postgres dump and a tgz containing the media files, located in `fixtures`
2. A script that populates the Mastodon backend with test data (`restore-mastodon-data.js`).
The reason we don't use a Postgres dump for everything
is that Mastodon will ignore changes made after a certain period of time, and we
don't want our tests to randomly start breaking one day. Running the script ensures that statuses,
favorites, boosts, etc. are all "fresh".
### Updating the test data
You probably don't want to do this, as the `0xx` tests are pretty rigidly defined against the test data.
Write a `1xx` test instead and insert what you need on-the-fly.
If you really need to, though, you can either:
1. Add new test data to `mastodon-data.js`
1. Comment out `await restoreMastodonData()` in `run-mastodon.js`
2. Make your changes manually to the live Mastodon
3. Run the steps in the next section to back it up to `fixtures/`
### Updating the Mastodon version
1. Run `rm -fr mastodon` to clear out all Mastodon data
1. Comment out `await restoreMastodonData()` in `run-mastodon.js` to avoid actually populating the database with statuses/favorites/etc.
2. Update the `GIT_TAG` in `mastodon-config.js` to whatever you want
3. If the Ruby version changed (check Mastodon's `.ruby-version`), install it and update `RUBY_VERSION` in `mastodon-config.js` as well as the Ruby version in `.github/workflows`.
4. Run `yarn run-mastodon`
5. Run `yarn backup-mastodon-data` to overwrite the data in `fixtures/`
6. Uncomment `await restoreMastodonData()` in `run-mastodon.js`
7. Commit all changed files
8. Run `rm -fr mastodon/` and `yarn run run-mastodon` to confirm everything's working
Check `mastodon.log` if you have any issues.
Note that we also run `db:migrate` just to play it safe, but
updating the `fixtures/` should make that a no-op.
## Unit tests
There are also some unit tests that run in Node using Mocha. You can find them in `tests/unit` and
run them using `yarn run test-unit`.
2019-09-21 20:44:32 +00:00
## Debug build
To disable minification in a production build (for debugging purposes), you can run:
DEBUG=1 yarn build
## Debugging Webpack
The Webpack Bundle Analyzer `report.html` and `stats.json` are available publicly via e.g.:
- [](
- [](
This is also available locally after `yarn run build` at `.sapper/client/report.html`.
## Deploying
This section only applies to `` and ``, not if you're hosting your own version of
The site uses [Vercel]( The `master` branch publishes to `` and the `production`
branch deploys to ``.
## Architecture
See [](
## Internationalization
See [](