docs: consolidate, update and extend documentation (#967)

Author: sebthom

.github/workflows/build.yml

@@ -9,6 +9,7 @@ on:  # https://docs.github.com/en/actions/reference/workflows-and-actions/events
     - '**'
     paths-ignore:
     - '**/*.md'
+    - '**/*.png'
     - '.github/*.yml'
     - '.github/workflows/bump-version.yml'
     - '.github/workflows/codeql.yml'
@@ -22,6 +23,7 @@ on:  # https://docs.github.com/en/actions/reference/workflows-and-actions/events
   pull_request:
     paths-ignore:
     - '**/*.md'
+    - '**/*.png'
     - '.github/*.yml'
     - '.github/workflows/bump-version.yml'
     - '.github/workflows/codeql.yml'

.github/workflows/codeql.yml

@@ -9,6 +9,7 @@ on:  # https://docs.github.com/en/actions/reference/workflows-and-actions/events
     branches: [ "main" ]
     paths-ignore:
     - '**/*.md'
+    - '**/*.png'
     - '**/.project'
     - '**/.settings/*.prefs'
     - '.gitignore'
@@ -18,6 +19,7 @@ on:  # https://docs.github.com/en/actions/reference/workflows-and-actions/events
     branches: [ "main" ]
     paths-ignore:
     - '**/*.md'
+    - '**/*.png'
     - '**/.project'
     - '**/.settings/*.prefs'
     - '.gitignore'

.github/workflows/markdown-lint.yml

@@ -0,0 +1,60 @@
+# https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax
+name: Markdown Lint
+
+on:  # https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows
+  push:
+    branches-ignore:  # build all branches except:
+    - 'dependabot/**'  # prevent GHA triggered twice (once for commit to the branch and once for opening/syncing the PR)
+    tags-ignore:  # don't build tags
+    - '**'
+    paths:
+    - '**/*.md'
+  pull_request:
+    paths:
+    - '**/*.md'
+  workflow_dispatch:
+    # https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#workflow_dispatch
+
+
+defaults:
+  run:
+    shell: bash
+
+
+jobs:
+
+  ###########################################################
+  markdown_lint:
+  ###########################################################
+
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+    - name: "Show: GitHub context"
+      env:
+        GITHUB_CONTEXT: ${{ toJSON(github) }}
+      run: echo $GITHUB_CONTEXT
+
+
+    - name: "Show: environment variables"
+      run: env | sort
+
+
+    - name: Git Checkout
+      uses: actions/checkout@v6  # https://github.com/actions/checkout
+
+
+    - name: "Install: Node"
+      uses: actions/setup-node@v6
+      with:
+        node-version: lts/*
+
+
+    - name: Install markdownlint-cli
+      run: npm install -g markdownlint-cli
+
+
+    - name: Run markdownlint
+      run: markdownlint "**/*.md"

.markdownlint.yaml

@@ -0,0 +1,11 @@
+# https://github.com/DavidAnson/markdownlint#optionsconfig
+MD004: false  # ul-style
+MD012: false  # no-multiple-blanks
+MD013: false  # line-length
+MD031: false  # blanks-around-fences
+MD032: false  # blanks-around-lists
+MD033: false  # no-inline-html
+MD034: false  # no-bare-urls
+MD045: false  # no-alt-text
+MD049: false  # emphasis-style
+MD060: false  # table-column-style

.markdownlintignore

@@ -0,0 +1,4 @@
+_LOCAL
+org.eclipse.tm4e.language_pack/syntaxes/
+**/target/
+org.eclipse.tm4e.core.tests/src/main/resources/test-cases/

CONTRIBUTING.md

@@ -21,11 +21,12 @@ For more information, please see the Eclipse Committer Handbook: https://www.ecl
 
 ## 💬 Get in touch with the community
 
-Eclipse TM4E use mainly 2 channels for strategical and technical discussions
+Eclipse TM4E uses the following channels for strategical and technical discussions:
 
-- 🐞 View and report issues through uses GitHub Issues at https://github.com/eclipse/m2e-tm4e/issues.
-- 📧 Join the tm4e-dev@eclipse.org mailing-list to get in touch with other contributors about project organization and planning,
-  and browse archive at 📜 https://accounts.eclipse.org/mailing-list/tm4e-dev
+- 🐞 View and report issues through GitHub Issues at https://github.com/eclipse-tm4e/tm4e/issues.
+- 💬 Ask questions, propose ideas, and discuss features in GitHub Discussions at https://github.com/eclipse-tm4e/tm4e/discussions.
+- 📧 Join the tm4e-dev@eclipse.org mailing list to get in touch with other contributors about project organization and planning,
+  and browse the archive at 📜 https://accounts.eclipse.org/mailing-list/tm4e-dev
 
 
 ## 🆕 Trying latest builds
@@ -35,77 +36,22 @@ Latest builds, for testing, can be found at https://download.eclipse.org/tm4e/sn
 
 ## 🧑‍💻 Developer resources
 
-### ⌨️ Setting up the Development Environment manually
+For regular contributors and maintainers, the main technical reference is the [TM4E Contributor Guide](docs/contributor-guide.md). It covers:
 
-1. Download and install the **Eclipse IDE for Eclipse Committers** from https://www.eclipse.org/downloads/packages/ or another
-   Eclipse installation with the [Plug-in Development Environment (PDE)](https://www.eclipse.org/pde/) installed.
-1. Clone this repository <a href="https://mickaelistria.github.io/redirctToEclipseIDECloneCommand/redirect.html"><img src="https://mickaelistria.github.io/redirctToEclipseIDECloneCommand/cloneToEclipseBadge.png" alt="Clone to Eclipse IDE"/></a>.
-1. _File > Import > Existing Maven Project_, select the path to the TM4E Git repository and import projects and all modules
-   ![](documentation/import_project.png)
-1. To solve the compiler errors, open the [target-platforms/oldest.target](target-platforms/oldest.target) file in Eclipse, wait until all dependencies are resolved, and click on _**Set as Active Target Platform**_
-   ![](documentation/configure_target_platform.png)
+- Repository and module structure.
+- Development environment setup and target platform configuration.
+- Build and test workflows (command line and within Eclipse).
+- Diagnostics and troubleshooting (traces, test generation, token hover).
+- Versioning and the TM4E release process.
 
 ### 🏗️ Build & Test
 
-1. **On command line**
+If you just want to run the full build locally, the short version is:
 
-   On Windows execute `mvnw clean verify`\
-   On Linux execute `./mvnw clean verify`
+- On Windows: `mvnw clean verify`
+- On Linux/macOS: `./mvnw clean verify`
 
-2. **Within Eclipse**
-
-   - To run full Maven builds: Having [M2E](https://www.eclipse.org/m2e/) installed, right-click on the tm4e root folder > _Run As > Maven build_
-
-   - To run the non-UI tests of any imported module, right-click on the respective project and select > _RunAs > JUnit Test_
-
-   - To run the UI tests, right-click on the `org.eclipse.tm4e.ui.tests` project and select > _RunAs > JUnit Plug-in Test_
-
-3. **Running the CI job locally:**
-
-    TM4E's [GitHub Actions wokflow](.github/workflows/build.yml) is compatible with [nektos/act](https://github.com/nektos/act) a
-    command-line tool that allows you to run GitHub Actions workflows locally.
-
-    1. Install Docker
-    1. Install [nektos/act](https://github.com/nektos/act)
-    1. From the command line navigate into the tm4e project root
-    1. Run the command `act`
-    1. On subsequent re-runs you can use `act -r` to reuse previous container which avoids re-installation system packages and
-       reduces build times.
-
-    In case of build failures the docker container will still be running and you can SSH into it for analysis
-    using `docker exec -u root -it <CONTAINER_ID> /bin/bash`, e.g.:
-    ```bash
-    container_id=$(docker container ps --filter status=running --filter name=act-Build-build --format {{.ID}})
-    docker exec -u root -it $container_id /bin/bash
-    ```
-
-### ⬆️ Version bump
-
-The TM4E project adopts [Semantic Versioning](https://semver.org/) on release level, ensuring the proper exposure of API contracts
-and addressing potential breakages.
-
-To alleviate confusion among end-users regarding the effectively installed TM4E release and to ease the development process and
-troubleshooting, starting with version **0.9.0**, individual TM4E features/plugins are no longer versioned independently
-(OSGi semantic versioning). Instead, they are aligned with the overall TM4E release version, following a practice that is common
-in other Eclipse Platform projects, such as EGit, Mylyn, or Xtext, as well as popular projects outside the Eclipse Platform
-universe, like the Spring Application Framework or Quarkus.
-
-In this versioning approach, when any plugin introduces new features necessitating a minor version increment, the versions of
-**all** TM4E plugins/features are updated collectively, and the next release version will be adjusted accordingly.
-
-To simplify version increments, utilize the `bump-versions.py` Python script located in the root project directory. This script
-facilitates the recursive update of the project version and plugin dependencies in all relevant files, including `pom.xml`,
-`feature.xml`, and `META-INF/MANIFEST.MF`.
-
-The usage is as follows:
-```bash
-$ python bump-version.py (major|minor|micro)
-```
-
-Where
-- `micro` (`+0.0.1`) is for a backward compatible bugfix, or an internal change that doesn't surface to APIs
-- `minor` (`+0.1.0`) is for a backward compatible API or feature addition
-- `major` (`+1.0.0`) is for an API breakage (needs to be discussed on the mailing-list first)
+For everything beyond that, including IDE setup and CI-style runs with `act`, please refer to `docs/contributor-guide.md`.
 
 ### ➕ Submit changes
 
@@ -126,18 +72,4 @@ To send us a pull request, please:
 GitHub provides additional documentation on [forking a repository](https://help.github.com/articles/fork-a-repo/) and
 [creating a pull request](https://help.github.com/articles/creating-a-pull-request/)
 
-### Release
-
-1. Decide of a version name, we'll call it `x.y.z` here. Ensure all plugins have this version set in their MANIFEST.MF.
-   You can use the `bump-versions.py` Python script to set the version as needed.
-1. Get the main code locally, e.g.: `git fetch eclipse main && git checkout FETCH_HEAD`
-1. Tag it `git tag x.y.x`
-1. Push tag, e.g. `git push eclipse x.y.z`
-1. Re-run a build from https://ci.eclipse.org/tm4e/job/TM4E/job/main/ and ensure it passes
-1. Upon completion of the build, run https://ci.eclipse.org/tm4e/job/promote-snapshot-to-release/ with version `x.y.z`
-1. Create a new `x.y.z` release entry on GitHub, from the `x.y.z` tag.
-1. Create a new `x.y.z` release entry on https://projects.eclipse.org/projects/technology.tm4e
-1. Create a PR to update https://github.com/eclipse-simrel/simrel.build/blob/main/tm4e.aggrcon
-   - For SimRel release dates see https://github.com/eclipse-simrel/.github/blob/main/wiki/Simultaneous_Release.md
-1. (Optionally) Announce on mailing-lists. social media...
-1. Run `python bump-version.py patch` and commit all changed pom.xml/feature.xml/MANIFEST.MF files to `main` branch
+For release engineering details (version bumping, CI promotion, SimRel updates), see the "Extension and API Evolution Guidelines" and "Release Process" sections in `docs/contributor-guide.md`.