Update docs in preparation for 1.0.0 release (#205)

- Created changelog and releasing markdown files
- Update contribution guidelines to help better setup for development
- Added reference to CI jobs
- Update all screenshots in README to be consistent with current source
- Added a Version Support table to the readme

Fixes #204
Part of #209

Author: jonahgraham

CHANGELOG.md

@@ -0,0 +1,7 @@
+## CDT LSP Change Log
+
+### v1.0.0 (Sep 2023)
+
+- First release of CDT LSP
+
+Fixed issues: <https://github.com/eclipse-cdt/cdt-lsp/milestone/1?closed=1>

CONTRIBUTING.md

@@ -12,11 +12,16 @@ To try out and develop the plug-ins in you can edit and run them from source.
 1. Setup a CDT development environment following the instructions in [CDT's contributing instructions](https://github.com/eclipse-cdt/cdt/blob/main/CONTRIBUTING.md#contributing-to-cdt).
 2. Clone this repo
 3. Import the plug-ins in this repo into Eclipse development environment from Step 1
-4. Launch the Eclipse IDE with this Pug-ins tab settings from the launch config: *All workspace and enabled target Pug-ins* from your development IDE
+4. Consider closing the `org.eclipse.cdt.lsp.examples.*` projects as they demonstrate how to extend CDT LSP and may affect the overall behaviour, for example by removing the "Prefer C/C++ Editor (LSP)" checkbox.
+5. Launch the Eclipse IDE with this Pug-ins tab settings from the launch config: *All workspace and enabled target Pug-ins* from your development IDE
 
 ## CI Builds
 
 All PRs are built using GitHub Actions using the workflows in the [.github/workflows](.github/workflows) directory.
 
 All branches are built using the [Jenkinsfile](Jenkinsfile) on the [Eclipse Foundations Jenkins infrastructure](https://wiki.eclipse.org/Jenkins) in the [cdt-lsp](https://ci.eclipse.org/cdt/job/cdt-lsp) multi-branch pipeline.
 The pipeline publishes continuously to download.eclipse.org, for example the `master` branch publishes to https://download.eclipse.org/tools/cdt/builds/cdt-lsp/master/
+
+## CI Milestone and Release Builds
+
+The [cdt-lsp](https://ci.eclipse.org/cdt/job/cdt-lsp) multi-branch pipeline's build results can be published as milestones or release builds by using the [promote-a-build](https://ci.eclipse.org/cdt/job/promote-a-build/) building with parameters and choosing the CDT repo and branch to publish.

README.md

@@ -2,18 +2,57 @@
 
 **Target audience** are Eclipse plugin developers who want to use/develop a LSP based C/C++ Editor.
 
-This plugin is based on the [LSP4E](https://github.com/eclipse/lsp4e) and [TM4E](https://github.com/eclipse/tm4e) Eclipse projects. The editor is based on the `ExtensionBasedTextEditor` in Eclipse.
+This plugin is based on the [LSP4E](https://github.com/eclipse/lsp4e) and [TM4E](https://github.com/eclipse/tm4e) Eclipse projects. The editor is based on the [`ExtensionBasedTextEditor`](https://github.com/eclipse-platform/eclipse.platform.ui/blob/master/bundles/org.eclipse.ui.genericeditor/src/org/eclipse/ui/internal/genericeditor/ExtensionBasedTextEditor.java#L55-L56) in Eclipse.
 
-The `org.eclipse.cdt.lsp` is the core plugin. C/C++ IDE Developers can use the `serverProvider` extension point to define a C/C++ language server. If there is no extension defined, the LLVM [clangd](https://clangd.llvm.org/) language server will be used and searched on the PATH environment variable. Clangd searches for a `compile_commands.json` file in the source file folder and its parents. It's needed to determine the compile informations. In the default clangd configuration, the PATH will be searched for a `gcc` compiler to determine the default compiler include paths.
+The [`org.eclipse.cdt.lsp`](https://github.com/eclipse-cdt/cdt-lsp/tree/master/bundles/org.eclipse.cdt.lsp) is the core plugin. C/C++ IDE Developers can use the [`serverProvider`](https://github.com/eclipse-cdt/cdt-lsp/blob/master/bundles/org.eclipse.cdt.lsp/schema/serverProvider.exsd) extension point to define a C/C++ language server. If there is no extension defined, the LLVM [clangd](https://clangd.llvm.org/) language server will be used and searched on the PATH environment variable. Clangd searches for a `compile_commands.json` file in the source file folder and its parents. It's needed to determine the compile informations. In the default clangd configuration, the PATH will be searched for a `gcc` compiler to determine the default compiler include paths.
 
 The editor is basically the `ExtensionBasedTextEditor`. The language grammar comes from [TM4E](https://github.com/eclipse/tm4e). 
 
 ![screenshot.png](images/screenshot.png "screenshot.png")
 
+<!-- 
 
+For regenerating the overall screenshot create a new CMake project in Eclipse called
+something similar to HelloCMake and use this contents for the main file to allow
+showing the following features:
+
+- Project Explorer expanded to show outline
+- Outline View
+- hover over something from the std library
+- Open type hierarchy for Message
+- Open call hierarchy for display
+
+#include <iostream>
+using namespace std;
+
+class Message {
+public:
+  virtual void display() = 0;
+};
+
+class HelloWorld : Message {
+public:
+  void display() { cout << "Hello World" << endl; }
+};
+
+class CDTDoesLsp : Message {
+public:
+  void display() { cout << "CDT does LSP" << endl; }
+};
+
+int main() {
+  HelloWorld hw;
+  hw.display();
+  CDTDoesLsp cdt;
+  cdt.display();
+
+  return 0;
+}
+
+-->
 
 The Editors features depends on the support on client ([LSP4E](https://github.com/eclipse/lsp4e)) and server ([clangd](https://clangd.llvm.org/)) side.
-Currently these feature are supported (clangd 15.0.3) and current LSP4E:
+Currently these feature are supported (clangd 15 and 16) and current LSP4E:
 
 - Auto completion
 - Hovering
@@ -22,7 +61,7 @@ Currently these feature are supported (clangd 15.0.3) and current LSP4E:
 - Find References
 - Code actions (Declare implicit copy/move members, Extract to function/variable, rename)
 - Quick Fix (Ctrl+1)
-- Type hierarchy (quick hierarchy view only) 
+- Type hierarchy
 - Call hierarchy
 - Outline view
 
@@ -49,8 +88,10 @@ see [issues](https://github.com/eclipse-cdt/cdt-lsp/issues)
 
 ## Try it out
 
-1. Download the latest Developer Build of Eclipse for C/C++ Developers or Eclipse for Embedded C/C++ Developers using the [Eclipse installer](https://www.eclipse.org/downloads/packages/installer) or downloading and extracting the latest milestone available on [eclipse.org](https://www.eclipse.org/downloads/packages/release/).
-2. Add `https://download.eclipse.org/tools/cdt/builds/cdt-lsp/master/` to your Available Software Sites and install *C/C++ LSP Support* in the *Eclipse CDT LSP* Category and restart Eclipse.
+1. Download the latest Developer Build of Eclipse for C/C++ Developers or Eclipse for Embedded C/C++ Developers using the [Eclipse installer](https://www.eclipse.org/downloads/packages/installer) or downloading and extracting the latest release available on [eclipse.org](https://www.eclipse.org/downloads/packages/release/).
+2. Add to your Available Software Sites and install *C/C++ LSP Support* in the *Eclipse CDT LSP* Category and restart Eclipse from one of these p2 sites:
+    - For latest release: `https://download.eclipse.org/tools/cdt/releases/cdt-lsp-latest`
+    - For current master branch continuous build: `https://download.eclipse.org/tools/cdt/builds/cdt-lsp/master/`
 3. [Install Pre-requisites](#install-pre-requisites) listed below
 4. [Create a CMake project](#create-an-example-cmake-project) or [import an existing](#import-an-existing-project) project following guidelines below
 5. [Enable the LSP based C/C++ Editor](#activating-lsp-based-cc-editor) following instructions above.
@@ -87,7 +128,7 @@ This file may be hidden by default, therefore to see the file uncheck the *.\* r
 By default C/C++ will be opened with the standard CEditor.
 The default can be changed per project or per workspace with the *C/C++ General* -> *Editor (LSP)* -> *Prefer C/C++ Editor (LSP)* checkbox in the project setting or preferences.
 
-- Note: The workspace setting will be used for new projects only. To use the LSP based editor on a project, *Prefer C/C++ Editor (LSP)* must be activated in the project properties.
+- Note: The workspace setting will be used for projects that have not checked the *Enable project specific settings* checkbox in the project properties -> *C/C++ General* -> *Editor (LSP)* page.
 
 Alternatively, you can choose which editor to open the file by using *Open With*:
 
@@ -98,6 +139,17 @@ With the *C/C++ Editor (LSP)* open, the presentation of the C++ file will follow
 
 ![hello-world.png](images/hello-world.png "hello-world.png")
 
+### Version Support
+
+The following table shows the versions of the main dependencies of CDT LSP for best operation as developed and tested.
+For example, CDT LSP 1.0.x was developed against clangd 15.0.x but CDT LSP should work with newer versions of clangd as well.
+For plug-in dependencies the MANIFEST.MF's dependency information will provide the most accurate information.
+
+| CDT LSP Version | clangd | cmake* | Eclipse IDE Release |
+|:-:|:-:|:-:|:-:|
+| 1.0.x | 15.0.x | 3.x | 2023-09 |
+
+\* cmake is required to run through the demo flow, but any tool that can create compile_commands.json or otherwise feed settings to clangd is suitable.
 
 ### Known issues
 

RELEASING.md

@@ -0,0 +1,45 @@
+This is the Release plan and TODO list for CDT LSP.
+
+## Steps for Release
+
+Items at the beginning of development
+
+- [ ] Create an Endgame Issue to track the release. As a starting point use [RELEASING.md](https://github.com/eclipse-cdt/cdt-lsp/blob/master/RELEASING.md).
+    - [ ] Add the [Endgame](https://github.com/eclipse-cdt/cdt-lsp/labels/endgame) label
+- [ ] Create a [New milestone](https://github.com/eclipse-cdt/cdt-lsp/milestones/new) for the release, and if available add a due date 
+    - [ ] Apply the milestone to the endgame issue
+- [ ] Ensure all previous [Endgame issues](https://github.com/eclipse-cdt/cdt-lsp/labels/endgame) are done.
+    - [ ] Make sure any previous edits made to [Endgame issues](https://github.com/eclipse-cdt/cdt-lsp/labels/endgame) of previous releases are updated in [RELEASING.md](https://github.com/eclipse-cdt/cdt-lsp/blob/master/RELEASING.md)
+- [ ] Update version numbers on master branch (after the release branch was created), this is generally the next minor version (or major version if that is what the committers on the project agree) and applies to the following types of files:
+    - [ ] `feature.xml` version
+    - [ ] `pom.xml` version
+    - It does not apply to versions in MANIFEST.MF which follow [API rules](https://github.com/eclipse-cdt/cdt/blob/main/POLICY.md#api).
+- [ ] Ensure [the CI build](https://ci.eclipse.org/cdt/job/cdt-lsp/job/master/) is stable - it is always better to release a "Green Dot" build
+
+Items in the days ahead of Release day:
+
+- [ ] Create release on [PMI](https://projects.eclipse.org/projects/tools.cdt) (e.g. `1.0.0 (CDT LSP)`)
+    - [ ] Fill in the *Review Documentation* -> *New & Noteworthy URL* with the [CHANGELOG.md](https://github.com/eclipse-cdt/cdt-lsp/blob/master/CHANGELOG.md)
+- [ ] Check [CHANGELOG.md](https://github.com/eclipse-cdt/cdt-lsp/blob/master/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](https://github.com/eclipse-cdt/cdt-lsp/blob/master/README.md) is up to date, in particular:
+    - [ ] the planned release and which versions of main dependencies are supported in the version support table
+    - [ ] screenshots are up to date and consistent
+    - [ ] try it out steps are correct and where suitable versions are up to date
+- [ ] Check all closed PRs and Issues to make sure their milestone is set. [This search may be useful to identify such closed issues](https://github.com/eclipse-cdt/cdt-lsp/issues?q=is%3Aclosed)
+- [ ] Create a branch for the release
+- [ ] Create the endgame for the next scheduled release right away and update the versions on the master branch
+
+Items on Release day:
+
+- [ ] Run [the CI build](https://ci.eclipse.org/cdt/job/cdt-lsp/) for the branch
+- [ ] Mark the build as Keep Forever and add the version to the description
+- [ ] Create a GitHub releases page (like https://github.com/eclipse-cdt/cdt-lsp/releases/tag/CDT_LSP_1_0_0)
+- [ ] [Promote a cdt build from jenkins](https://ci.eclipse.org/cdt/job/promote-a-build/) to releases
+- [ ] Add description to the promote-a-build job and the job it promoted.
+- [ ] Unmark as keep all old Milestone and RC jobs
+- [ ] Update or create [composites](https://github.com/eclipse-cdt/cdt/tree/main/releng/download/releases) in preparation for going public on release day
+  - [ ] Include the update to latest URL https://download.eclipse.org/tools/cdt/releases/cdt-lsp-latest to point to latest release
+- [ ] Tag the release. Example: `git tag -a CDT_LSP_1_0_0 HEAD -m"CDT LSP 1.0.0" && git push origin CDT_LSP_1_0_0`
+- [ ] Create a [release page on github](https://github.com/eclipse-cdt/cdt-lsp/releases/new)
+- [ ] Publish the GitHub release page
+- [ ] Forward the GitHub release page email to cdt-dev