Mismatch between master and releases

[Zambito1]

I ran into a confusing situation where I was trying to use the example from both the readme on github, and the manual book site for the working-directory attribute, and it simply said the attribute did not exist, despite using the latest release of just. I realized this attribute has been added since the latest release, and resolved my issue by installing just with cargo install just --git https://github.com/casey/just.git, specifying that it should be built from git.

Ideally, I think the latest documentation should reflect the latest release, rather than things that have not yet been released. This would have avoided the confusion. Though, this also would have made it less likely for me to find the working-directory attribute, so maybe it is just time for a new release :-)

[casey]

Which attribute? I try to remember to add <sup>master</sup> to unreleased features, which means that they're only available on master.

I'm not sure there's a great solution here. The readme will always reflect what's in master, and the manual at just.systems could be updated with every release, however it means that between releases, it wouldn't get updates and improvements to the docs which are unrelated to new features.

[Zambito1]

working-directory. I do see that it has master now, but it is in the table of all attributes, which is far from the documentation for how the attribute works.

This could be solved by reserving master for releases (a la git flow), and doing development off of a dev branch. Or maybe something similar to what Jujutsu does for their documentation. Their documentation is versioned per release, along with a prelease version that is built from their main branch.

https://martinvonz.github.io/jj/v0.24.0/

https://martinvonz.github.io/jj/prerelease/

I'm not sure if the book UI that is used for the just documentation currently supports publishing multiple versions though.

[casey]

I changed the action workflows to only publish to just.systems on release in #2516. It's slightly annoying that between releases the docs will lag, but I think probably better than the confusion that can arise with unreleased features, and if it's annoying, we can always change it back.