How to Avoid Breaking the Rascal Bootstrap

We are currently at the brink of switching to a development cycle where we critically depend on previously compiled code (e.g. Kernel, ParserGenerator). This page is intended to get an overall picture of breaking changes and how to remedy them.

Please:

• Add missing scenarios
• Correct scenarios
• Add validation per scenario (how has this scenario been tested?)

Scenarios that will break the bootstrap (✔️ means we tested this scenario)

• Make any test fail *

Any failing test will make the bootstrap halt. There is no other way then to fix the bug or adapt the test such that it makes sense again.

• Changing parameters of commandline tools rascalc, compileMuLibrary

Since the Bootstrap script depends on these parameters, and it calls both the previous versions from the jar and the new versions in the bin folder, the commandline parameters must never change without an intermediate step.

Workaround:

1. Support transition in Bootstrap script by case distinction of phase 1 and phase 2 (to use old parameters) and phase 3 and phase 4 to use the new parameters.
2. Bootstrap and release
3. Change Bootstrap script to remove case distinctions
4. Bootstrap and release

Scenarios that do not break the bootstrap (✔️ means we tested this scenario):

• renaming a MuPrimitive; ok if you change the compiler to generate the new name and the MuPrimitive name as well
• renaming a RascalPrimitive;
• changing the signature of a MuPrimitive
• changing the signature of a RascalPrimitive
• Changing Rascal functions other than Kernel functions
• Changing Java code that is unrelated to serialization
• Adding a Rascal language feature (e.g. coroutines) Note: any changes to the existing implementation should be handled according to the above approaches.
• Changing IValue or Type internally, i.e. no API changes
• Adding new IValues or Types
• Change signature of Kernel function rascalTests
• Adding field to a serialized Java class, e.g. RVMExecutable
• Delete a field from a serialized class

Scenarios to be validated/checked (break or not break):

• Changing name/signature of Kernel functions

  Approach:

  1. First follow below working bootstrap: "Add new kernel function"
  2. Release a stable version
  3. Then follow below working bootstrap: "Remove unused kernel function"

• Changing a constructor in the RVM datatype

  Approach: add new version and make old version deprecated

• Switching to automatic compression: |compressed+file:///.../Fac.rvm.ser.gz| to |file:///.../Fac.rvm.ser.gz|

  Approach: unclear

• Switching serialization format BinaryReader+FST => FlatBuffers

  Approach: this looks like a huge event; no clear solution

• Moving the compiler sources to another location

  Approach: this looks like a huge event; no clear solution

  Note: if the tests run after this move, then I don't see a problem for the bootstrap not to work.

• Deleting a Rascal language feature (e.g. annotations)

  Approach:

  1. Remove all uses of the feature from any Rascal code used for bootstrapping (e.g. Kernel, ParserGenerator, ...).
  2. Bootstrap.
  3. Remove the implementation of feature to be deleted.
  4. Bootstrap.