delay doc publishing until a release is tagged

[bjaglin]

New features/deprecations should not be publicly documented until a corresponding release is cut. mdoc is now run as part of the CI workflow to limit the risk of docs/docusaurusPublishGhpages failing at release time (would a doc change breaking mdoc be visible only on master now?).

This came up as I realized I should hold #1155 & #1160 (granted, it's not a big deal if I don't) after seeing the SNAPSHOT version in https://scalacenter.github.io/scalafix/docs/users/installation.html#help. Holding documentation PRs is hard to manage - we would need GitHub milestones to handle them properly?.

Once #1146 is done, the concept of release will be local, so another strategy will need to be found.

[bjaglin]

dead conf?

[olafurpg]

Looks dead

[olafurpg]

I would recommend against this change since it’s desirable to be able to update the documentation after a release based on user feedback. I still haven’t found an ideal solution for dealing with this problem, versioned documentation pages have their issues as well. It works best in my experience to update docs on every commit, release frequently and try to document all stable versions together in the same document (tables showing compatible matrix etc)

[olafurpg]

Looks dead

[bjaglin]

Thanks for the feedback @olafurpg! I am new to this, so I naively thought this would be better, but it's not that simple indeed.

it’s desirable to be able to update the documentation after a release based on user feedback

Without going the full way of an (over-engineered) versioned documentation, we could have a docs branch that we merge master into or reset to master on each tag/release, on which we could cherry-pick doc changes that apply / are relevant to the latest stable. Any push on that branch (and on that branch only) would trigger doc publishing. I am expecting such changes to be rare and the cost of cherry-picking to be acceptable, but that might be a biased assumption.

However, as sbt-scalafix and scalafix-core drift apart lifecycle/version-wise, this would no longer work unless the sbt-specific pages are migrated to sbt-scalafic repo (with potentially the same strategy), so the website becomes the combination of both docs. Maybe it's slightly off topic and should rather be discussed in #1146, but do you have some thoughts on this?

[olafurpg]

I haven't used a custom branch strategy in any projects so I'm not sure how it would work in practice. I suspect I personally would think it requires too much manual effort to cherry-pick commits into the docs branch.

In Metals, we have an mdoc:since modifier that allows us to declare in what Metals version a feature got released and mdoc displays a warning if the latest stable version is older than the version where the feature got released.

https://github.com/scalameta/metals/blob/8d0924af4348dcad0a2ae8a228c9d2f1fdcbff55/metals-docs/src/main/scala/docs/VersionedDocsModifier.scala

We haven't used mdoc:since much, but I think it's a decent solution to this problem where you want to document new features as early as possible without confusing users with documentation of features that are not available in the stable release.

With all things considered, my recommendation would be to continue updating docs on every merge into master and hold off merging PRs documenting new functionality.

[bjaglin]

With all things considered, my recommendation would be to continue updating docs on every merge into master and hold off merging PRs documenting new functionality.

Makes sense, thanks for sharing your experience!