search

eclipse / omr

Eclipse OMR™ Cross platform components for building reliable, high performance language runtimes
http://www.eclipse.org/omr
Other
940 stars 394 forks source link

WIP: Guide for migrating extensible class functionality from OMR to downstream projects #2079

Open 0xdaryl opened 6 years ago

0xdaryl commented 6 years ago

This issue describes the general process of relocating Eclipse OMR compiler functionality from an OMR extensible class into a downstream project (such as Eclipse OpenJ9). I would like to reference this issue within other refactoring issues as a guide to developers new to the process to ensure it happens smoothly with few problems. This process applies primarily to functionality in OMR extensible classes. Details on such classes can be found here https://github.com/eclipse/omr/blob/master/doc/compiler/extensible_classes/Extensible_Classes.md.

TBD I will be using issue https://github.com/eclipse/omr/issues/2061 as a working example to make this guide more concrete.

The best way to do this is to stage your changes so that you don't require near-simultaneous commits in two different projects. You may be able to pull this off if you can coordinate the efforts of two committers (or a single committer if she has rights in both repos), but it's best not to rely on that. One might argue that it is slower (or even more work) to stage your changes, but my experience refactoring 500 kLOC has been to stage the changes across repos to ease integration problems and assist with triage should things go wrong.

The general process is:

  1. Duplicate the functionality in the downstream project. Be sure the functionality moves into the corresponding class (a project class, an architecture specialization class, or a sub-architecture specialization class) in the downstream project.

    Ensure that the extensible class structure is maintained in the downstream project. This means, for example, that if you move a function in an architecture-specialized class downstream you must also create an empty project-specific class as its parent (unless one already exists).

  2. Test the change in the downstream project. Be sure you are testing against an OMR that contains the functionality that you are relocating downstream. This ensures that an OMR with the original functionality and the downstream project with the duplicated functionality can co-exist and build and test successfully.

  3. Create a PR in the downstream project and wait for it to be merged.

  4. In the meantime, you can work on removing the functionality from the Eclipse OMR project. Create a PR and mark it as a WIP. Also, if this commit will completely address the issue you're resolving add a "Closes" tag to the pull request body.

  5. Test the OMR PR on its own (e.g., use the CI mechanism) and test it in a build of the downstream project that integrates both the PR from step 3 and the OMR PR from step 4.

  6. When the downstream PR from step 3 has been merged and OMR testing from step 5 is successful, remove the WIP from the PR title.

0xdaryl commented 6 years ago

It is likely this issue could move into its own document if it has longevity.