Developing SweetPea

This section of the guide explains how to work on development of the SweetPea domain-specific language.

Configuring Your Development Environment

SweetPea is developed on Python 3.7.9. Unless a backwards-incompatible version of Python is released, SweetPea should run without issue on newer versions, but we require compatibility with 3.7.9, so we recommend using that for all SweetPea development.

Like with development of any Python package, use of a virtual environment is recommended.

Installing Dependencies

SweetPea’s required third-party libraries are recorded in the requirements.txt file at the root of the repository. You can install the needed libraries with pip by doing:

$ pip install -r requirements.txt

Repository Organization

The repository follows a particular structure:

Directory

Purpose of Contents

/

Various top-level files.

/.github/workflows/

GitHub Workflows for continuous integration.

/acceptance/

Specialized regression tests.

/docs/

All documentation.

/docs/_build/

Where documentation gets built to.

/docs/_source/

Sources for documentation generation.

/example_programs/

Examples of using SweetPea in code.

/sweetpea/

Actual SweetPea implementation code.

/sweetpea/core/

Back-end core implementation code.

/sweetpea/sampling_strategies/

Code for various sampling strategies.

/sweetpea/tests/

The test suite.

Note

In the rest of the documentation, we leave out the initial / of paths when discussing code in the SweetPea repository.

Workflows

SweetPea uses GitHub Workflows to perform continuous integration testing and handle other jobs. The workflows are written in YAML and their specifications live in .github/workflows/. The workflows we currently use are:

acceptance-fast.yml

Runs the default (non-slow) tests in acceptance/. This usually takes around 10 minutes to complete if there are no failures.

Triggers whenever a push includes changes in the following paths:

  • .github/workflows/acceptance-fast.yml

  • requirements.txt

  • acceptance/**

  • sweetpea/**

acceptance-slow.yml

Runs all tests in acceptance/. This usually takes close to 20 minutes to complete if there are no failures.

Triggers on pull requests or whenever a push modifies the .github/workflows/acceptance-slow.yml file.

gh-pages.yml

Publishes the GitHub Pages website.

Triggers when a push includes changes in the docs/_build/html/** path. This means that to trigger an update in the GitHub Pages, you must build the documentation and push the resulting changes to that directory.

platform-report.yml

Provides information about the platforms used when running the workflows.

This workflow never runs automatically. It must be run manually, either through the web interface or by using the GitHub Actions API. (You probably never need to run it, though.)

tests.yml

Runs the test suite in sweetpea/tests/.

Triggers on pull requests and whenever a push includes changes in the following paths:

  • .github/workflows/test.yml

  • requirements.txt

  • sweetpea/**

typecheck.yml

Runs the mypy static type checker to inspect the code for type correctness.

Triggers on pull requests and whenever a push includes changes in the following paths:

  • .github/workflows/typecheck.yml

  • sweetpea/**

Pull Requests

We will review all good-faith pull requests. For information on creating a pull requests, see GitHub’s documentation on the matter.