Contribute to the Lab Manual

Lab Operations
Collaboration
Propose, develop, preview, and submit changes to the Pollack Group Lab Manual.

Goal

Contribute corrections, new documentation, or new recipes to the Pollack Group Lab Manual.

Minor edits can be proposed directly through GitHub. Larger changes should be developed locally so that the manual can be previewed before submitting a pull request.

Prerequisites

For local development:

Procedure

1. Discuss substantial additions when appropriate

For a substantial new Guide page or Cookbook recipe, consider opening a GitHub issue before beginning implementation.

For new recipes in particular, the issue can be used to discuss:

  • the scope of the recipe;
  • whether an existing recipe already addresses the task;
  • where the recipe belongs in the Cookbook;
  • appropriate categories and metadata; and
  • related Guide pages and recipes.

Small corrections do not require an issue.

2. Create a branch

From an up-to-date local copy of the repository:

git switch -c descriptive-branch-name

Use a concise name that describes the proposed change.

3. Install the manual environment

pixi install

The Pixi environment provides Python and other dependencies used by executable content in the manual. Quarto itself is installed separately.

4. Make your changes

Guide pages explain concepts, practices, and the reasoning behind lab workflows.

Cookbook recipes document recurring, multi-step lab procedures. New recipes should follow RECIPE_TEMPLATE.qmd.

5. Preview while you work

From the root of the repository:

quarto preview

Quarto will open a local version of the manual and automatically update it as source files change.

Use the preview to inspect:

  • page content and formatting;
  • navigation;
  • internal and external links;
  • callouts;
  • code output; and
  • changes to _quarto.yml or site styling.

Stop the preview server with Ctrl+C.

6. Fully render the manual

Before committing the finished contribution, render the entire website:

quarto render

A successful preview does not replace this step. A full render checks the complete Quarto project and updates any executable content that needs to be recomputed.

Do not proceed until the full render completes without errors.

Executable content

The manual uses Quarto’s freeze functionality for executable content.

If you modify a .qmd file containing executable Python code, render it locally using the appropriate environment before submitting the pull request:

quarto render

Updated computational results under _freeze/ should be included in the commit when Quarto generates them.

This allows the published manual to use locally verified computational results without requiring the publishing workflow to reproduce every research environment used by the documentation.

7. Review your changes

Check:

git status

and, when useful:

git diff

Make sure the contribution does not contain unrelated files, generated content that should be ignored, credentials, or other unintended changes.

8. Commit and push

Stage the intended changes:

git add <files>

Commit them:

git commit -m "Describe your changes"

Then push your branch:

git push -u origin descriptive-branch-name

9. Open a pull request

Open a pull request into main on GitHub.

Describe:

  • what you changed;
  • why the change is useful;
  • any decisions that would benefit from discussion; and
  • anything reviewers should specifically test.

Address review comments on the same branch. Additional commits pushed to that branch will automatically appear in the pull request.

Once the pull request has been reviewed and merged into main, the lab manual’s publishing workflow will automatically rebuild and deploy the website.

Verify

Before requesting merge, confirm that:

  • quarto preview runs successfully;
  • changed pages render correctly;
  • internal and external links work;
  • new recipes contain appropriate metadata; and
  • files unrelated to the contribution have not accidentally been included.

Common problems

The manual does not render

Review the Quarto output.

Python packages are missing

The manual’s Python dependencies are managed with Pixi. Do not install a required project dependency manually into the environment. Add it through Pixi so that the environment definition and lock file remain reproducible.