Skip to content

Latest commit

 

History

History
44 lines (27 loc) · 3.99 KB

CONTRIBUTING.md

File metadata and controls

44 lines (27 loc) · 3.99 KB
Raw

Contributing

Polly uses GitHub for discussions and pull requests. In this early phase, there are a few different key ways to contribute:

  1. Writing test cases/examples
  2. Spec development
  3. Adding an object type

And of course, there's also the good first issue and help wanted issue labels!

Exploration by example

Polly is in an exploratory prototype phase. We're still deciding how some of its basic mechanisms will work. The fastest way for answers to reveal themselves is by actually trying to make polly packages (pops), and see what issues arise.

This is also a great way for (perseverent) folks to get a sense of what Polly is: try to make a pop, and put it up in a PR for discussion of questions or insights you may have had. (Especially if the result really didn't work out!)

If you want to give this a shot, here's a procedure:

  1. Install the cue CLI tool.
  2. Clone this repository.
  3. Pick a system to observe. (Strongly recommended: pick a system with an existing mixin to migrate)
  4. Pick some generally sensible name for the pop, based on the system you intend to observe. Create a directory with that name under examples/.
  5. Look at other examples to see how the pop is structured and how to use the various object types.
  6. Create your own! If you're adapting an existing mixin, it's easiest to pick out some subset of the objects to copy over. Consider taking notes about what you're thinking as you go through.
  7. Send a PR with your pop! We have a template with questions to help guide your response. Unfortunately, having multiple PR templates doesn't work well; you can manually append ?template=example_explore.md to the PR URL, or the gh CLI tool will give you a choice when running gh pr create.

NOTE: for new CUE-ers, there are tutorials; worth spending some time on, and the play site is a great testing sandbox.

Example pops may eventually mature to the point where they're moved out into their own repositories/wherever makes sense. For now, this keeps all the attention in one place, which is good for maximizing learning!

Specification development

The canonical polly specification - expressed in CUE - resides in this repository. All changes to the specification are conducted through reviews and pull requests against this repository.

The specification is being actively developed (read: unstable). While that is the case, we expect to proceed with a relatively informal pull request workflow: think of a change, make a PR, discuss on the fly. As the specification matures, we expect to put in place a more formal proposal process, especially for more significant proposals.

Adding an object type

Polly is designed to be extensible in specific ways. Chief among these is the ability to add new types of configuration objects to the specification.

This is less of a focus for now, in Polly's early phases of development. However, anyone interested in adding configuration for an appropriate type of object is welcome to make a proposal - we'll treat it as a forcing function to clarify the rules! For now, we're pretty sure this is key:

  1. The object's schema must be defined using scuemata
  2. The mechanism for (integrating a signal)[#6] into the config object must be defined