[GR-19691] Add documentation about releases and needing to mx sforceimports.

PullRequest: truffleruby/1764

Author: eregon

README.md

@@ -120,6 +120,12 @@ try running your full Rails application on. However it is ready for
 experimentation and curious end-users to try on their gems and smaller
 applications, and to send us reports of issues they find.
 
+## Releases
+
+TruffleRuby has the same version and is released at the same time as GraalVM.
+There is a release every 3 months, see the [release roadmap](https://www.graalvm.org/docs/release-notes/version-roadmap/).
+There are additional Critical Patch Update releases which are based on regular releases and include extra security fixes.
+
 ## Migration from MRI
 
 TruffleRuby should in most cases work as a drop-in replacement for MRI, but you

doc/contributor/workflow.md

@@ -84,6 +84,25 @@ Note that build information such as the date and Git revision hash will not be
 updated when you build for a second time. Releases should always be built from
 scratch.
 
+### Using the correct version of the graal repository
+
+TruffleRuby needs the `truffle` and `sulong` suites from the `graal` repository.
+`jt build` will automatically clone the repository but not enforce a specific version (commit).
+When running `jt build`, you might see an early warning:
+```
+$ jt build
+$ mx --env jvm scheckimports --ignore-uncommitted --warn-only
+WARNING: imported version of sulong in truffleruby (89aaf87268) does not match parent (aa6d8e07a6)
+You might want to run "mx sforceimports" to use the imported version or update the import with "mx scheckimports"
+```
+
+This warning is important.
+If you did not create new commits  in `graal`, you will typically need to run `jt mx sforceimports`
+so that a known compatible commit of `graal` is used (that commit is recorded in `mx.truffleruby/suite.py`).
+
+This is not done automatically, because sometimes you might want to have changes in `graal`,
+and because developers of the Truffle or Sulong team typically want to use a different commit of `graal` to test their changes.
+
 ### Building C Extensions more quickly
 
 To speed up compilation of bundled C extensions, it is possible to use

doc/user/debugging.md

@@ -4,12 +4,12 @@
 
 There are two ways to print exceptions, which can be useful to find the source of an error:
 
-* the standard Ruby `-d` flag which print the `file:line` where each exception was raised.
+* the standard Ruby `-d` flag which prints the `file:line` where each exception was raised.
 * `--backtraces-raise` which show the full backtrace on each exception raised.
 
 Both print all exceptions even if the exceptions are later rescued.
 
-Java exceptions can be printed with `exceptions-print-uncaught-java` or
+Java exceptions can be printed with `--exceptions-print-uncaught-java` or
 `--exceptions-print-java`.
 
 See other `--backtraces-*` and `--exceptions-*` options for more possibilities.