poly :all
The curious are most welcome, but we wrote this document for folks who are (or want to) contribute to the development poly
itself.
We very much appreciate contributions from the community.
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 are also happy to chat about your idea or fix on the Clojurians polylith channel. |
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.md.
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.
poly
ArgumentsSome poly
arguments are special-case or poly
developer-focused.
For this reason, the shell will not include these arguments in its autocomplete suggestions by default.
Most special arguments tweak the output of the various poly
commands.
all
- shell
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:
poly :all
changed-files
Have poly
react as if specified files have changed.
We use this to support testing poly
itself.
poly info changed-files:components/file/src/polylith/clj/core/file/core.clj
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:
poly info changed-files:bases/mybase/:components/mycomponent/:projects/myproject/
fake-sha
Fake the Git sha
output by the info command.
We use this to generate consistent info
output and screenshots for our documentation.
poly info fake-sha:c91fdad
fake-tag
Fake the Git tag
for output by the info command.
We sometimes use this to generate consistent info
output and screenshots for our documentation.
poly info fake-tag:stable-lisa
If you want no Git tag
to be shown in info
output:
poly info fake-tag:
fake-poly
Fake that you are using a stable production release of poly
when you might actually be using a SNAPSHOT
release, polyx
, or both.
poly help :fake-poly (1)
polyx :fake-poly (2)
1 | Excludes -SNAPSHOT from the version at the top of the help output |
2 | Shows poly instead of polyx and excludes -SNAPSHOT from the Polylith ASCII art logo |
This can be handy when capturing output for docs.
hide-lib-size
If :hide-lib-size
is given to the libs command, values in the KB
column appear as -
:
poly libs :hide-lib-size (1)
This is used in tests to guarantee that the output will look the same, regardless if a library has been downloaded or not.
latest-sha
Populate the latest-sha
from your Git repository in your workspace structure (by default, poly
does not populate this value).
poly ws get:settings:vcs:polylith:latest-sha :latest-sha
no-changes
Fake that there are no changes to your workspace since the last stable point in time; can be useful when generating output for docs.
# Returns no rows:
poly diff :no-changes
# Gets rid of the * characters:
poly info :no-changes
# ...has the same effect as:
poly info changed-files:
no-exit
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.
replace
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.
poly ws get:settings:user-home
On Joakim’s system, output is:
"/Users/joakimtengstrand"
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:
poly ws get:settings:user-home replace:$HOME:MY-HOME
Outputs a user-generic:
"MY-HOME"
Another example:
poly ws get:settings:user-config-filename replace:$HOME:MY-HOME
Outputs a user-generic:
"MY-HOME/.polylith/config.edn"
An example with multiple replacements:
poly ws get:settings:user-config-filename replace:$HOME:MY-HOME:config.edn:USER-CONFIG
Outputs:
"MY-HOME/.polylith/USER-CONFIG"
Sometimes you need to deal with your OS shell escaping rules and add, for example, ""
.
poly ws get:settings:vcs:stable-since:sha replace:"[0-9]+":"*"
The output will vary because git shas are unique, but on Joakim’s system once:
"*e*d*b*cee*fb*e*ff*fafcf"
We strive to write great documentation for our Polylith users.
AsciiDoc is thoughtfully designed for writing articles; we like that, so all of our articles are written in AsciiDoc.
Some conventions we have found helpful are:
Write one sentence per line. Among other things, this helps us to avoid run-on sentences.
These particular docs cover an implementation of a Polylith tool, so use the concrete poly
instead of the abstract "Polylith tool".
For command-line poly create workspace top-ns:my-ns branch:my-branch :commit
refer to:
create workspace
as a command
top-ns:my-ns
, branch:my-branch
and :commit
as arguments
Link to referenced commands and concepts to make it easier for readers to explore and dig into details.
Use the AsciiDoc keyboard macro for keyboard shortcuts. For an example usage, see Shell page.
Use "we" when talking from the Polylith core team and "you" when directing the reader through some steps or a tutorial.
Try to maintain a casual and friendly tone.
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:
Inkscape source: ./doc/images/doc/doc-overview.svg
Exported png: ./doc/images/doc/doc-overview.png
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:
Use a transparent background.
We host our docs on cljdoc, which uses a light theme. Folks viewing our docs on GitHub might have opted for a dark theme, so choose colors that will also be dark-theme friendly.
Choose cross-platform-friendly fonts.
Courier New
and Arial
seem to be what existing diagrams use.
If you are a Linux user, you can install these as part of Microsoft’s fonts.
We host our docs on cljdoc, which generates docs for our:
API by analyzing our source code from our release jar
pages (which cljdoc calls "articles") which cljdoc finds under doc, and whose layout is defined by doc/cljdoc.edn.
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:
git clone git@github.com:polyfy/polylith.git
Take a look at the help for our babashka doc-preview
task:
$ cd polylith
$ bb doc-preview help
Commands:
start Start docker containers supporting cljdoc preview
ingest Locally publishes poly for cljdoc preview
view Opens cljdoc preview in your default browser
stop Stops docker containers supporting cljdoc preview
status Status of docker containers supporting cljdoc preview
help Show this help
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):
$ bb doc-preview start
$ bb doc-preview ingest
Commit and push all your changes before you ingest .
|
Bring the docs up in your web browser with:
bb doc-preview view
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
.
clojure -M:poly :local
Now docs open in your browser against the locally running cljdoc:
polylith$ doc page:component
From time to time, there is a new release of cljdoc. To pick it up:
bb doc-preview stop
bb doc-preview start
When you’ve changed the polylith codebase, you need to run ingest
again (no need to stop
and start
):
bb doc-preview ingest
Examples of when you might want to ingest
are when you have:
Switched to a different git branch.
Pulled changes down with git pull
.
Pushed commits with git push
.
You must commit and push your changes for ingest
to function; doing so from a branch is fine.
Fire up a shell:
clojure -M:poly :local
Specify the :github
argument to bring up the page in your web browser on GitHub:
polylith$ doc page:component :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
:
polylith$ doc page:component branch:issue-318 :github
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:
clojure -M:poly :github
polylith$ doc page:component
poly
So long as you’ve cloned the polylith
workspace locally, you can access it from other workspaces.
This can be convenient when testing another workspace but wanting to use a local polylith
that has some work in progress.
Let’s say you have cloned the Realworld example app as a sibling to the polylith
repo in your directory tree.
You could then replace the :poly
alias in clojure-polylith-realworld-example-app/deps.edn
:
...
:poly {:main-opts ["-m" "polylith.clj.core.poly-cli.core"]
:extra-deps {polylith/clj-poly {:local/root "../polylith/projects/poly"}}} (1)
1 | Notice the .. relative path to poly |
And now, from the clojure-polylith-realworld-example-app
dir, you can launch local poly
via, e.g.:
clojure -M:poly
Clojure tools.deps only checks for updates once per day by default.
This caching behavior means users referencing a specific SNAPSHOT
will be more likely to temporarily be on an older release if you frequently release under the same SNAPSHOT
version.
Users can -Sforce a check for an update, but most probably won’t think to do that.
Run all the tests:
poly test :all
If you have made a lot of changes, run the gen-all
script (this will take a few minutes):
bb gen-all
Compare the output with what’s in git, and commit the changes if everything looks good.
Make a 0.2.20-SNAPSHOT #34
release:
Update the version
component and ensure that:
Ensure the versions are correctly specified in readme.adoc
:
snapshot-version is set to 34
.
stable version is set to current stable version, 0.2.19
.
snapshot version is set to 0.2.20-SNAPSHOT
.
Verify that we have included everything in next-release.md.
Commit and push your changes.
Go to the polylith repo and prepare to merge the snapshot-022034
branch into master
, by clicking the "Compare & pull requests" button at the top.
If the circlci pipeline is green, merge it into the master
branch.
Execute git switch master
followed by git pull
to get the latest from master
.
Execute (depending on what the next release should be):
git switch -c snapshot-022035
if the next release should be a 0.2.20-SNAPSHOT #35
release.
git switch -c release-0220
if the next release should be a 0.2.20
release.
In this example, we work with 0.2.20-SNAPSHOT #34
from the snapshot-022034
branch, and want to create a 0.2.20
release out of it.
Run all the tests:
poly test :all
Run the gen-all
script (this will take a few minutes):
bb gen-all
Compare the output with what’s in git, and commit and push the changes if everything looks good.
Create a 0.2.20-SNAPSHOT #34
release (if you refer to the release, make sure you separate # and 34 so that you don’t link to old issues and PRs).
Announce in good time in the polylith channel in Slack, that people should start testing current SNAPSHOT version. Also mention that there will only be minor changes until release, such as updating the documentation. Wait a few days before you make the new release.
Make a 0.2.20
release:
Execute git switch master
followed by git pull
to get the latest.
Create the release branch by executing git switch -c release-0220
.
Update the version
component and ensure that:
Ensure the versions are correctly specified in readme.adoc
:
snapshot-version is set to 0
.
stable version is set to current stable version, 0.2.20
.
snapshot version is set to 0.2.20-SNAPSHOT
.
Update the doc and its navigation:
If a page has been added to the doc directory, also add it to cljdoc.edn and execute this function to generate the doc navigation.
If a blog post, video or high-level doc page has been added, then update more.clj.
If any doc content has been added, make sure to update corresponding examples in the doc, e.g. what more outputs.
Search for occurrences of :poly-version:
constants, and set the version to 0.2.20
wherever it appears (at the top of .adoc files).
Commit and push your changes.
Build a local version of Cljdoc:
Check that new content looks correct.
Verify that we have included everything in next-release.md.
Check that the badges at the top and the API at the bottom left are displayed correctly (most namespaces should begin with a ^:no-doc
tag, to exclude them from the API doc).
Go to the polylith repo and prepare to merge the release-0220
branch into master
, by clicking the "Compare & pull requests" button at the top.
Add a comment indicating that this is release 0.2.20.
If the circlci pipeline is green, merge it into the master
branch.
Ensure that the poly-clj documentation has been built, and verify that the badges at the top and the API at the bottom left are displayed correctly.
Update the release notes for the 0.2.20 release:
Summarize the release in the introduction.
Copy the content from next-release.md into the release notes.
Execute git switch master
followed by git pull
to get the latest from master.
Execute git switch -c snapshot-032101
to create a first snapshot branch for the next release (here we imagine that the next release is 0.3.21).
Create a 0.3.21-SNAPSHOT #1
release, see make a snapshot release for instructions.
Announce in #releases in clojurians in Slack, by summarizing the most important changes + the included issues and PRs + add a link to the #polylith channel.
Announce on X (Twitter) and maybe other places.
Archive the Done column on the KanBan board.
Can you improve this documentation?Edit on GitHub
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close