Developing poly

If you have an idea or a fix, please do raise a GitHub issue before investing in any coding effort. That way, we can discuss first. Writing code is the easy part; maintaining it forever is the hard part!

That said, if you notice a simple typo, a PR without an issue is fine.

We expect you to include/update tests for your change.

You’ve probably gotten the sense that providing good docs for our users is important to us. When your change affects our docs or needs to be described for our users, we expect you to do so.

Add a brief line summarizing your change to next-release.adoc. The poly core team moves the content in this file to the changelog for each stable release.

Please never force push on your PR, as this makes reviewing incremental changes impossible for us. When we merge your PR, we’ll usually squash it, so that will clean up any rambling work-in-progress.

By default, the shell does not suggest special poly arguments because they are irrelevant and inappropriate for typical users of poly. If you are developing poly itself, suggesting special poly arguments can be appropriate and meaningful. To start a shell with autocomplete suggestions enabled for all poly arguments:

Have poly react as if specified files have changed. We use this to support testing poly itself.

More than one file can be faked as changed by separating them with colons.

Specify a brick or project path with a trailing forward slash, and poly will treat the brick or project as changed:

Fake the Git sha output by the info command. We use this to generate consistent info output and screenshots for our documentation.

Fake the Git tag for output by the info command. We sometimes use this to generate consistent info output and screenshots for our documentation.

If you want no Git tag to be shown in info output:

Fake that you are using a stable production release of poly when you might actually be using a SNAPSHOT release, polyx, or both.

This can be handy when capturing output for docs.

Populate the latest-sha from your Git repository in your workspace structure (by default, poly does not populate this value).

Fake that there are no changes to your workspace since the last stable point in time; can be useful when generating output for docs.

By default, poly explicitly exits via System/exit . If executing poly from a REPL, this will also exit the REPL, which probably isn’t what you want. To avoid that, specify :no-exit.

See poly-cli source comment block for plenty of examples.

Manipulate output from the ws command.

You can tell the ws command to search for strings (using regular expressions) and replace the occurrences with another string.

On Joakim’s system, output is:

But maybe we want some repeatable output for test or documentation purposes, regardless of which user is running the ws. Assuming that your HOME environment variable is set appropriately and that you are running from your OS shell (not poly’s shell):

An example:

Outputs a user-generic:

Another example:

Outputs a user-generic:

An example with multiple replacements:

Outputs:

Sometimes you need to deal with your OS shell escaping rules and add, for example, "".

The output will vary because git shas are unique, but on Joakim’s system once:

We create our diagrams with the ever-so-awesome Inkscape. Inkscape’s native format is .svg. We export to .png for use in our documentation. We keep the source .svg beside the exported .png in our GitHub repo.

We store doc images under ./doc/images/, for example for the overview diagram in ./doc/doc.adoc doc:

Generated images (currently from bb create-example via polyx) are grouped with their related images but are prefixed with an output dir. This strategy helps us distinguish hand-crafted images from generated ones and reminds us not to edit images in the output dirs.

Sometimes, we’ll annotate a generated image. We do so via an Inkscape SVG file and link (rather than embed) the generated image. As of this writing, if any of these images change, the .svg will have to be manually re-exported to its .png.

Tips:

We host our docs on cljdoc, which generates docs for our:

We have cljdoc build our docs each time we release to clojars. This includes SNAPSHOT releases, which we create for every successful push to master. See Polylith CI Setup for more details.

When making changes to docs, you can preview what they will look like on cljdoc. If you have not already done so, clone the polylith repository:

Take a look at the help for our babashka doc-preview task:

Start the server and publish the documentation locally (the first start will take some time to download the cljdoc docker image, and ingest is on the slow side):

Bring the docs up in your web browser with:

If you are in the polylith workspace root directory (which is also the git repo root dir), you can start a shell specifying the :local argument to tell the doc command to open pages on https://localhost:8000 instead of https://cljdoc.org.

Now docs open in your browser against the locally running cljdoc:

From time to time, there is a new release of cljdoc. To pick it up:

When you’ve changed the polylith codebase, you need to run ingest again (no need to stop and start):

Examples of when you might want to ingest are when you have:

Fire up a shell:

Specify the :github argument to bring up the page in your web browser on GitHub:

If you started your shell from the polylith repository (not a fork), then pages will automatically be opened in your current working branch; otherwise, pages will open on the master branch.

To choose a specific branch:

If you aren’t running cljdoc locally, you may want to always open pages on GitHub instead of cljdoc; specify the :github argument when starting a shell: