Contributing

If you’d like to contribute to Observable Framework, here’s how. First clone the git repo and run Yarn Classic to install dependencies:

git clone [email protected]:observablehq/framework.git
cd framework
yarn

Next start the local preview server:

yarn dev

Lastly visit http://127.0.0.1:3000.

The local preview server restarts automatically if you edit any of the TypeScript files, though you may need to reload. The default page is docs/index.md; if you edit that file and save changes, the live preview in the browser will automatically update.

To generate the static site:

yarn docs:build

This creates the docs/.observablehq/dist folder. View the site using your preferred web server, such as:

http-server docs/.observablehq/dist

This documentation site is built on GitHub using Observable Framework; see the deploy workflow. Please open a pull request if you’d like to contribute. Contributors are expected to follow our code of conduct. 🙏

A test coverage report can be generated with c8, in text and lcov formats, to help you identify which lines of code are not (yet!) covered by tests. Just run:

yarn test:coverage

Releasing

To release a new version, first update the package.json file by following the standard process for committing code changes:

1. Create a new branch.
2. Edit the version field in the package.json file as desired.
3. Commit your change to your branch.
4. Push your branch up to GitHub.
5. Open a pull request and ask for a review.
6. Once approved, merge your pull request to the main branch.

Once the above is done, you can publish the release via GitHub:

1. Go to Draft a new release.
2. Under Choose a tag, enter the new version with a v e.g. v1.2.3.
3. Click Create new tag: v1.2.3.
4. Leave the Target as main.
5. Click Publish release.

That’s it! The publish action will take care of the rest.