That's why the gitbook stuff is moving to here https://github.com/polyfy/polylith/tree/issue-318/doc (note: the issue-318 branch).

You can open regular issues on the polylith repo for documentation problems, and issue 318 is completed and merged, you'd be able to provide PRs to, if you want.

thank you kindly

(I think Joakim is only planning to move the tool docs to the GH repo -- the high-level overview docs may stay in GitBook for the time being... but I hope that all moves too at some point)

Yeah, I've been working on this switch for quite a while now. When it's ready to be pushed to master, a 0.2.18-SNAPSHOT versions of the documentation will be available on clojars (and updated versions of that snapshot when more issues are included in the release) before the 0.2.18 is released, so be patient for a little while longer!

My English is not perfect unfortunately, so I will let an English speaker go through all the documentation before it's merged into master. I'm still working on it, but if you @U05HNU149J9 or anyone else here feels they want to help out with that work, don't hesitate to contact me!

yes, i’d be happy to help out in the meantime i opened https://github.com/polyfy/polylith/pull/324 on the https://github.com/polyfy/polylith/tree/issue-318 branch - a namespace mismatch that had me scratching my head until i cross-referenced it with the example code

Okay, cool, and thanks for the PR!

I'd create a 3rd branch and merge/rebase in the two branches I was interested in.

ok maybe I didn't describe what I want well enough. In the same editor I'd like to be able to work on two libraries (components, or bases, I guess in polylith terms) of a monorepo at once, alternating between the two as I please, but if I want to work on two different branches of that monorepo, one for each library, then I can't because I can only check out one at a time

So you would like to switch between two different versions of a component?

no, between one branch of the whole monorepo to work on one component, and another branch to work on another component

I know that you can do such things in git, to check out one directory from one branch (or even a different repo). I haven’t tried it out myself, so I don’t remember the syntax. I will be busy in a few minutes, so I don’t have time to check it out for you, unfortunately.

@U0CKDHF4L IMO, that kind of goes against the whole ethos of a monorepo -- you want everything consistent so you want a single branch with your changes on...

It would be interesting to hear about your use case @U0CKDHF4L.

only one branch ? what about components in development which aren't ready for deployment to production ?

Let's say we keep what's in production in the master branch. When we want to work on new functionality, we may create an issue in GitHub, and then we create a branch based on master e.g. issue-123. Now the code in that branch will look exactly the same as in master (including all our components) which means that we can make changes in the issue-123 branch without affecting master. When we feel we are ready with your changes, e.g. updated component x, then we merge issue-123 into master and deploy master to production. Did that answer your question?

I had gathered that much, but I'm used to having several different projects open, being able to switch between different branches as I please

Maybe a solution is to have a cloned repo per branch, each in a separate directory.

I had dismissed that idea for its ugliness

I get now though, Polylith enforces a linear synchronous working style

> I'm used to having several different projects open, being able to switch between different branches as I please Polylith is a monorepo system so you only have one project open that contains "everything". You can still switch between different branches, but the whole monorepo switches. On each branch, the whole monorepo is self-consistent. You no longer have the multi-version "assembly" aspect to deal with -- just a given version of "everything" at any point in time.

We have profiles for places where the actual dependencies matter (which, for us, is primarily about whether the code runs on JDK 8 for one legacy app or JDK 20 for everything else). Nearly all the (3rd party) deps -- libs -- are specified in bases/components as needed by their code with only a few deps specified in projects.

I'm not sure we are talking about the same thing. If we have a regular project and accompanying REPL to it, the dependency graph should keep parity (subject to change if you apply aliases - but aliases is something that explicitly screams "I'm going to alter your deps, expect changes"). While, with polylith we kind of diverge REPL dependency graph from prod's dependency graph (ending up with potentially different behaviour). The Rich's "Spec-ulation" talk refers to the problem of deps uncertainty. To me, polilyth, at the current design, invites disparity of dependencies/classpaths. I can be wrong though. Just wanted to post it in case someone thought already about it and share more reflections on this potential problem.

I don't follow you... when you build an artifact (application) from a Polylith monorepo, it's built from a single, consistent view (version) of the entire repository. There's no disparity there. Could you explain your concerns differently?

poly test is based on projects, so it tests what gets built.

I'm sorry. I don't have extensive experience with polylith and I haven't yet a demo project validating my concerns. I still consider I can be wrong. An artifact is built from within a project, while REPL starts from root. The dependency graph used by REPL is then bigger then of a project. That led me to conclusion that evaluating things within a REPL in polylith we can't have certainty we are using the exactly same set of dependencies as the production running artifact.

In practice, the REPL dependencies are nearly always a pure superset of any given project's dependencies so it's almost never a concern (see my comments about profiles previously for a specific way to deal with known differences in versions).

Like I say, we work with a REPL started from :dev:test with 140k lines of code in 160 bases/components building 20 projects at work and it's fine.

A single monorepo -- with 140k lines of Clojure and about 160 bases/components.

In our case, a single monorepo with just 16k lines of Clojure and 22 bases/components, but rapidly growing! I would be really interested to hear how teams handle CI builds in general under polylith. for instance, when component code changes, how do you just build the dependent projects? Do teams have a build step which moves a github stable tag or the like such that affected subsequent tests only are run? How do you know which projects this affected and that these need to be built (usually as uber jars and docker images)? We use github actions/workflows. I would rather not maintain the list of component paths in each of my project-level github workflows when that information is already in my project deps.edn, but it’s what I currently do…

@U0505U3TS90 I blogged about that: https://corfield.org/blog/2022/12/07/deps-edn-monorepo-10/ -- see "Polylith to the rescue, part 4" specifically.

Happy to answer any specific Qs you may have after reading that...

Yes, after revisiting your blog I can see you’ve already solved what I think most teams need. Afterall, one of the benefits of monorepos in general, such as Basel, is the incremental build capability that leverages explicit build dependencies. Now we can do this with Polylith on any version control system, which is neat. Thanks!