collect documentation about how to be a Scala module maintainer
SethTisue opened this issue · 17 comments
we should really collect this stuff in one place, and this repo seems like the logical place
see e.g. the comments at scala/scala-swing#51 — there is info from me about the expected commitment level to be a community maintainer, info on tagging and publishing, info from @andy1138 on CLA checking, etc
we've also held other maintainers' hands on this stuff (e.g. @biswanaths, @ashawley, @gourlaysama)
would someone like to volunteer to add the basic info to the README? it doesn't need to be super comprehensive or elaborate, just basics. in the long run we can grow and refine it
in addition to how-to information about what to do once you are already a maintainer, it could also include information about what being a maintainer even involves, for people considering volunteering. then we could add "volunteers wanted" links to it from the module READMEs
see e.g. @adriaanm's remarks at scala/scala-xml#60
There should be, but I don't recall any :-/
for the eventual doc: in addition to tagging and publishing, doing a module release should involve updating the module repo's "Releases" page so the release is marked as the latest release and includes release notes. see e.g. https://github.com/scala/scala-xml/releases . (I had to remind a new module maintainer about this recently.)
there are some nice docs here https://github.com/scala/scala-parallel-collections/blob/master/admin/README.md
some perhaps usable material or ur-material is here: scala/scala-swing#65 (comment)
I've written down some notes specific to scala-xml on the wiki that probably overlaps with other modules:
- https://github.com/scala/scala-xml/wiki/Contributor-guide
- https://github.com/scala/scala-xml/wiki/Maintainer-guide
I haven't made notes on anything about releases, but I'll probably make a separate guide for that.
about the CLA, previously: scala/scala-swing#51 (comment) so I think the status quo is that contributors are supposed to sign the CLA but we don't have automation for it in the module repos. this came up again at scala/scala-swing#68
how much freedom do module maintainers have to make changes? I wrote some remarks on this just now at scala/scala-swing#76 (comment)
@ashawley's scala/scala-xml#225 shows how to publish module Scaladoc to scala.github.io
how to publish module Scaladoc to scala.github.io
but also, there's been discussion at scala/scala-parallel-collections#27 on whether it might be adequate to just rely on javadoc.io for this
a recent development (@lrytz tackled it) has been centralizing Travis-CI configuration at https://github.com/scala/scala-dev/blob/scala-dev/travis/default.yml using Travis's new "include" feature. sample PR scala/scala-continuations#60
these days scala-xml has the "master" copy of build.sh. we propagate changes to other repos as needed
here's a checklist I've been using at publishing time:
- review build & CI configs and PR any needed version bumps, CI matrix changes, etc
- review/merge any outstanding PRs
- choose version number (backpublish? new version?)
- create/tag the release, including writing release notes
- wait for Travis-CI release build
- release the staging repos
- wait for artifacts to arrive on Maven Central
- post-release, bump version in README
- publicity?
The latest build.sh, by @lrytz, which I think I've now copied around to all of the modules (nearly all, anyway?), changes how backpublishing works.
The new way to backpublish is to remove the unwanted matrix entries from .travis.yml, then tag and push the commit (tagged, but not on any branch: git push origin <tag-name>, where the tag name would be something like v1.0.0#3.0.0-M2 where the Scala version after the # is actually ignored by the scripts, it's just documentation)
I did this recently over at scala/scala-parallel-collections#143 and it worked fine.
there was a question on the timing of accepting Scala 3 version upgrades in modules at scala/scala-xml#647 (comment)
in short:
- it's fine to upgrade to new patch versions immediately
- since the modules are at the base of many big dependency trees, we should be a bit cautious about adopting a new minor release like 3.2.0, since it forces the upgrade on everyone downstream — better to wait for 3.2.1 or 3.2.2
- when we do move to a new Scala 3 minor version, we should also bump the module's minor version
note that Scala 3 version numbers are major.minor.patch (whereas Scala 2 version numbers are epoch.major.minor)
note that many of the remarks from past years about publishing no longer apply since all of the modules are on sbt-ci-release now, so the standard sbt-ci-release procedure applies. there is no more build.sh
also
how to publish module Scaladoc to scala.github.io
it might be adequate to just rely on javadoc.io for this
this is the universal standard now