{"id": "contributing:contributing-formatting", "page": "contributing", "ref": "contributing-formatting", "title": "Code formatting", "content": "Datasette uses opinionated code formatters:  Black  for Python and  Prettier  for JavaScript. \n             These formatters are enforced by Datasette's continuous integration: if a commit includes Python or JavaScript code that does not match the style enforced by those tools, the tests will fail. \n             When developing locally, you can verify and correct the formatting of your code using these tools.", "breadcrumbs": "[\"Contributing\"]", "references": "[{\"href\": \"https://github.com/psf/black\", \"label\": \"Black\"}, {\"href\": \"https://prettier.io/\", \"label\": \"Prettier\"}]"}
{"id": "contributing:contributing-documentation", "page": "contributing", "ref": "contributing-documentation", "title": "Editing and building the documentation", "content": "Datasette's documentation lives in the  docs/  directory and is deployed automatically using  Read The Docs . \n             The documentation is written using reStructuredText. You may find this article on  The subset of reStructuredText worth committing to memory  useful. \n             You can build it locally by installing  sphinx  and  sphinx_rtd_theme  in your Datasette development environment and then running  make html  directly in the  docs/  directory: \n             # You may first need to activate your virtual environment:\nsource venv/bin/activate\n\n# Install the dependencies needed to build the docs\npip install -e .[docs]\n\n# Now build the docs\ncd docs/\nmake html \n             This will create the HTML version of the documentation in  docs/_build/html . You can open it in your browser like so: \n             open _build/html/index.html \n             Any time you make changes to a  .rst  file you can re-run  make html  to update the built documents, then refresh them in your browser. \n             For added productivity, you can use use  sphinx-autobuild  to run Sphinx in auto-build mode. This will run a local webserver serving the docs that automatically rebuilds them and refreshes the page any time you hit save in your editor. \n             sphinx-autobuild  will have been installed when you ran  pip install -e .[docs] . In your  docs/  directory you can start the server by running the following: \n             make livehtml \n             Now browse to  http://localhost:8000/  to view the documentation. Any edits you make should be instantly reflected in your browser.", "breadcrumbs": "[\"Contributing\"]", "references": "[{\"href\": \"https://readthedocs.org/\", \"label\": \"Read The Docs\"}, {\"href\": \"https://simonwillison.net/2018/Aug/25/restructuredtext/\", \"label\": \"The subset of reStructuredText worth committing to memory\"}, {\"href\": \"https://pypi.org/project/sphinx-autobuild/\", \"label\": \"sphinx-autobuild\"}]"}
{"id": "contributing:contributing-bug-fix-branch", "page": "contributing", "ref": "contributing-bug-fix-branch", "title": "Releasing bug fixes from a branch", "content": "If it's necessary to publish a bug fix release without shipping new features that have landed on  main  a release branch can be used. \n             Create it from the relevant last tagged release like so: \n             git branch 0.52.x 0.52.4\ngit checkout 0.52.x \n             Next cherry-pick the commits containing the bug fixes: \n             git cherry-pick COMMIT \n             Write the release notes in the branch, and update the version number in  version.py . Then push the branch: \n             git push -u origin 0.52.x \n             Once the tests have completed, publish the release from that branch target using the GitHub  Draft a new release  form. \n             Finally, cherry-pick the commit with the release notes and version number bump across to  main : \n             git checkout main\ngit cherry-pick COMMIT\ngit push", "breadcrumbs": "[\"Contributing\"]", "references": "[{\"href\": \"https://github.com/simonw/datasette/releases/new\", \"label\": \"Draft a new release\"}]"}
{"id": "contributing:devenvironment", "page": "contributing", "ref": "devenvironment", "title": "Setting up a development environment", "content": "If you have Python 3.8 or higher installed on your computer (on OS X the quickest way to do this  is using homebrew ) you can install an editable copy of Datasette using the following steps. \n             If you want to use GitHub to publish your changes, first  create a fork of datasette  under your own GitHub account. \n             Now clone that repository somewhere on your computer: \n             git clone git@github.com:YOURNAME/datasette \n             If you want to get started without creating your own fork, you can do this instead: \n             git clone git@github.com:simonw/datasette \n             The next step is to create a virtual environment for your project and use it to install Datasette's dependencies: \n             cd datasette\n# Create a virtual environment in ./venv\npython3 -m venv ./venv\n# Now activate the virtual environment, so pip can install into it\nsource venv/bin/activate\n# Install Datasette and its testing dependencies\npython3 -m pip install -e '.[test]' \n             That last line does most of the work:  pip install -e  means \"install this package in a way that allows me to edit the source code in place\". The  .[test]  option means \"use the setup.py in this directory and install the optional testing dependencies as well\".", "breadcrumbs": "[\"Contributing\"]", "references": "[{\"href\": \"https://docs.python-guide.org/starting/install3/osx/\", \"label\": \"is using homebrew\"}, {\"href\": \"https://github.com/simonw/datasette/fork\", \"label\": \"create a fork of datasette\"}]"}
{"id": "contributing:contributing-running-tests", "page": "contributing", "ref": "contributing-running-tests", "title": "Running the tests", "content": "Once you have done this, you can run the Datasette unit tests from inside your  datasette/  directory using  pytest  like so: \n             pytest \n             You can run the tests faster using multiple CPU cores with  pytest-xdist  like this: \n             pytest -n auto -m \"not serial\" \n             -n auto  detects the number of available cores automatically. The  -m \"not serial\"  skips tests that don't work well in a parallel test environment. You can run those tests separately like so: \n             pytest -m \"serial\"", "breadcrumbs": "[\"Contributing\"]", "references": "[{\"href\": \"https://docs.pytest.org/\", \"label\": \"pytest\"}, {\"href\": \"https://pypi.org/project/pytest-xdist/\", \"label\": \"pytest-xdist\"}]"}
{"id": "contributing:contributing-documentation-cog", "page": "contributing", "ref": "contributing-documentation-cog", "title": "Running Cog", "content": "Some pages of documentation (in particular the  CLI reference ) are automatically updated using  Cog . \n                 To update these pages, run the following command: \n                 cog -r docs/*.rst", "breadcrumbs": "[\"Contributing\", \"Editing and building the documentation\"]", "references": "[{\"href\": \"https://github.com/nedbat/cog\", \"label\": \"Cog\"}]"}
{"id": "contributing:contributing-formatting-blacken-docs", "page": "contributing", "ref": "contributing-formatting-blacken-docs", "title": "blacken-docs", "content": "The  blacken-docs  command applies Black formatting rules to code examples in the documentation. Run it like this: \n                 blacken-docs -l 60 docs/*.rst", "breadcrumbs": "[\"Contributing\", \"Code formatting\"]", "references": "[{\"href\": \"https://pypi.org/project/blacken-docs/\", \"label\": \"blacken-docs\"}]"}
{"id": "contributing:contributing-continuous-deployment", "page": "contributing", "ref": "contributing-continuous-deployment", "title": "Continuously deployed demo instances", "content": "The demo instance at  latest.datasette.io  is re-deployed automatically to Google Cloud Run for every push to  main  that passes the test suite. This is implemented by the GitHub Actions workflow at  .github/workflows/deploy-latest.yml . \n             Specific branches can also be set to automatically deploy by adding them to the  on: push: branches  block at the top of the workflow YAML file. Branches configured in this way will be deployed to a new Cloud Run service whether or not their tests pass. \n             The Cloud Run URL for a branch demo can be found in the GitHub Actions logs.", "breadcrumbs": "[\"Contributing\"]", "references": "[{\"href\": \"https://latest.datasette.io/\", \"label\": \"latest.datasette.io\"}, {\"href\": \"https://github.com/simonw/datasette/blob/main/.github/workflows/deploy-latest.yml\", \"label\": \".github/workflows/deploy-latest.yml\"}]"}
{"id": "contributing:contributing-formatting-prettier", "page": "contributing", "ref": "contributing-formatting-prettier", "title": "Prettier", "content": "To install Prettier,  install Node.js  and then run the following in the root of your  datasette  repository checkout: \n                 npm install \n                 This will install Prettier in a  node_modules  directory. You can then check that your code matches the coding style like so: \n                 npm run prettier -- --check \n                 > prettier\n> prettier 'datasette/static/*[!.min].js' \"--check\"\n\nChecking formatting...\n[warn] datasette/static/plugins.js\n[warn] Code style issues found in the above file(s). Forgot to run Prettier? \n                 You can fix any problems by running: \n                 npm run fix", "breadcrumbs": "[\"Contributing\", \"Code formatting\"]", "references": "[{\"href\": \"https://nodejs.org/en/download/package-manager/\", \"label\": \"install Node.js\"}]"}
{"id": "contributing:contributing-using-fixtures", "page": "contributing", "ref": "contributing-using-fixtures", "title": "Using fixtures", "content": "To run Datasette itself, type  datasette . \n             You're going to need at least one SQLite database. A quick way to get started is to use the fixtures database that Datasette uses for its own tests. \n             You can create a copy of that database by running this command: \n             python tests/fixtures.py fixtures.db \n             Now you can run Datasette against the new fixtures database like so: \n             datasette fixtures.db \n             This will start a server at  http://127.0.0.1:8001/ . \n             Any changes you make in the  datasette/templates  or  datasette/static  folder will be picked up immediately (though you may need to do a force-refresh in your browser to see changes to CSS or JavaScript). \n             If you want to change Datasette's Python code you can use the  --reload  option to cause Datasette to automatically reload any time the underlying code changes: \n             datasette --reload fixtures.db \n             You can also use the  fixtures.py  script to recreate the testing version of  metadata.json  used by the unit tests. To do that: \n             python tests/fixtures.py fixtures.db fixtures-metadata.json \n             Or to output the plugins used by the tests, run this: \n             python tests/fixtures.py fixtures.db fixtures-metadata.json fixtures-plugins\nTest tables written to fixtures.db\n- metadata written to fixtures-metadata.json\nWrote plugin: fixtures-plugins/register_output_renderer.py\nWrote plugin: fixtures-plugins/view_name.py\nWrote plugin: fixtures-plugins/my_plugin.py\nWrote plugin: fixtures-plugins/messages_output_renderer.py\nWrote plugin: fixtures-plugins/my_plugin_2.py \n             Then run Datasette like this: \n             datasette fixtures.db -m fixtures-metadata.json --plugins-dir=fixtures-plugins/", "breadcrumbs": "[\"Contributing\"]", "references": "[]"}
{"id": "contributing:general-guidelines", "page": "contributing", "ref": "general-guidelines", "title": "General guidelines", "content": "main should always be releasable . Incomplete features should live in branches. This ensures that any small bug fixes can be quickly released. \n                 \n                 \n                     The ideal commit  should bundle together the implementation, unit tests and associated documentation updates. The commit message should link to an associated issue. \n                 \n                 \n                     New plugin hooks  should only be shipped if accompanied by a separate release of a non-demo plugin that uses them.", "breadcrumbs": "[\"Contributing\"]", "references": "[]"}