LSP4J 1.0.0

[jonahgraham]

This is the Release plan and TODO list for LSP4J release v1.0.0.

Steps for graduation

• [x] #873
• [x] #874

Steps for Release

Items at the beginning of development

• [x] Create an Endgame Issue to track the release. As a starting point use documentation/releasing.md.
  • [x] Add the Endgame label and Milestone for the release
  • [x] Make sure any previous edits made to Endgame issues of previous releases are updated in documentation/releasing.md
• [x] Ensure all previous Endgame issues are done.
• [x] Create a New milestone for the release
• [x] Check CHANGELOG.md is up to date. The changelog should have a version entry, release date, API Breakages and other information consistent with current entries in the changelog.
• [x] Check README.md is up to date. In particular that the planned release and which versions of DAP and LSP are support is listed.
• [x] Increment version of all feature.xml, pom.xml and any other place full version is used. (Easiest way is global find and replace, e.g. s/0.24.0/1.0.0/g, s/0.23.0/0.24.0/g and review changes.) Ensure that -SNAPSHOT is restored in the gradle/versions.gradle and releng/pom.xml
• [x] Enable cd releng && ./deploy-build.sh' in releng/build.Jenkinsfile
• [ ] Ensure the CI build is stable - it is always better to release a "Green Dot" build

Items in the days ahead of Release day:

• [ ] Create release on PMI
• [ ] Schedule the release and if needed schedule a release review on the PMI. A release review is needed every 12 months, not with each release.
• [ ] Check CHANGELOG.md is up to date. The changelog should have a version entry, release date, API Breakages and other information consistent with current entries in the changelog.
• [ ] Check README.md is up to date. In particular that the planned release and which versions of DAP and LSP are support is listed.
• [ ] Check all closed PRs and Issues to make sure their milestone is set. (Note: this was not until after 0.10.0 release so many old PRs and Issues have no milestone, therefore only consider items back to approx 5 Nov 2020). This search may be useful to identify such closed issues
• [ ] Create and analyse a japicmp report and publish it as part of the build. Ensure that the API versions are incremented accurately based on the report. The reports are part of the build in japicmp-report and generated by releng/runjapicmp.sh
• [ ] Update links in changelog for japicmp from the nightly to the final location

Items on Release day:

• [ ] Prepare the repo for release by:
  • [ ] removing -SNAPSHOT from gradle/versions.gradle
  • [ ] removing -SNAPSHOT from releng/pom.xml entries in <dependencies> section.
  • [ ] disabling cd releng && ./deploy-build.sh' in releng/build.Jenkinsfile
  • see commit https://github.com/eclipse-lsp4j/lsp4j/commit/328ce8a4c89b0cd84fb62118f459b6cf79b09e90 for a past example
• [ ] Push the above change
• [ ] Run the CI build
• [ ] Mark the build as Keep Forever and add to the description v1.0.0
• [ ] Deploy the release by running the Release CI job with parameters:
  • LSP4J_PUBLISH_LOCATION -> updates/releases/1.0.0 ( <-- check version number)
  • PROJECT -> lsp4j-multi-build/job/main
  • LSP4J_BUILD_NUMBER -> the build that was just run above
  • DRY_RUN -> false
• [ ] Add to the deploy job description v1.0.0
• [ ] Promote the staged repository to maven central
  • Login to Nexus
    • To obtain permission add request to OSSRH-26079
  • go to Staging Repositories, after a short delay the staged LSP4J release should appear (you may need to press Refresh)
  • click the staged LSP4J repo
  • press the Close button located in the toolbar. This runs activities, including checking various rules
  • once the rules are done (if successful), press the Release button (you may need to press Refresh to enable the Release button)
  • check https://search.maven.org/search?q=g:org.eclipse.lsp4j to make sure the latest release has arrived - this takes a while, 15 minutes for the files to be on the server and even longer for the search indexes to update
• [ ] Update the meta-data on PMI downloads page
• [ ] Tag the release. Example: git tag -a v1.0.0 HEAD -m"LSP4J 1.0.0" && git push origin v1.0.0
• [ ] Contribute to Simrel. See Simrel contribution example
• [ ] Create a release page on github
• [ ] Link the Changelog to the release page
• [ ] Make an announcement on lsp4j-dev based on the release page on github. Example on lsp4j-dev archives
• [ ] Update documentation/releasing.md with any changes that may have been made to the release process.
• [ ] Create the endgame for the next release right away, especially as version numbers and restoring -SNAPSHOT need to be done right away.

[jonahgraham]

This is going to be the first release of the graduated LSP4J. Follow along the reviews in gitlab here.

[jonahgraham]

A first question is should we do LSP4J release 1.0.0 soon with basically the same contents as 0.24.0 minus deprecated code. This would be for 2025-03 time frame?

[jonahgraham]

I checked and LSP4E does not access any of the API I proposed removing in #874 so there should be little overhead for a second version bump. I have not investigated any of the other projects that depend on LSP4J directly yet.

[cdietrich]

Am not sure what will break and if I have time to adapt on Xtext side. this is about lsp4j deprecations, not lsp deprecation

[jonahgraham]

this is about lsp4j deprecations, not lsp deprecation

Yes - just LSP4J deprecations. I did an analysis in #874 - but the summary is that everything being removed (except javax.websocket #647) is trivially updateable to non-deprecated code.

[jonahgraham]

After being sidelined for a while I am back to work on this again.

When should we aim to do 1.0.0 release that includes all the recent improvements. @sebthom do you have any thoughts as many of the recent contributions & improvements are from you. Anyone else is very welcome to weigh in too.

[cdietrich]

as simrel have m3 early next week and rc1 the week after i'd perfer a release after 2025-12 due to the breaking changes and the need to adapt

[pisv]

@jonahgraham Welcome back, we missed you!

I'd be great if you could take a look at #893 and share your opinion about whether it should be released as part of 1.0.0 or make available in some other way (2.0.0-beta?). There are significant breaking changes there such as changing types of TextDocumentEdit.edits and Diagnostic.message that are in the draft (beta) state until LSP 3.18 is released. I'm not quite sure what would be the best way forward to release such changes.

[jonahgraham]

I'd be great if you could take a look at #893 [...]

Done https://github.com/eclipse-lsp4j/lsp4j/pull/893#pullrequestreview-3478788348

[jonahgraham]

In light of no one requesting an urgent release, lets look at releasing 1.0.0 soon after 2025-12 SimRel - so mid Dec to mid Jan timeframe, once we have stability and/or when a consumer asks nicely for a release soon.