A lot of tools, packages, and people using those tools depend on the PCM metamodel. As we have many developers that develop on the trunk version, i.e. the nightly build, we have to make sure that changes to the PCM RSA metamodel should be done carefully with respect to the breaking tools and the expected time it takes to fix code due to metamodel changes.
The main focus of the PCM metamodelling process is to avoid situations where a developer wants to create code based on metamodel changes he or she made, but the created code does not work because other metamodel changes have been made before for which no updated code has been generated. In many cases, these metamodel changes cannot be comprehended by the developer which prevents him from fixing the code errors.
The following process should therefore be used to develop the PCM w.r.t. metamodel changes.
The key factors of the process are:
- For major changes: Organize a metamodel review
- Document and communicate the metamodel changes
- Take care that
- Code is immediately being generated for the updated metamodel
- The major tools being used (Editors, templates, simulation, solvers) are working with the changes
- The changes are being tested
Organize a metamodel review
This should be done if major changes are being done.
The review should be used for
- meta-model (changes) quality assurance
- detecting the amount of tool changes that come with the metamodel change and if the tool changes are feasible
Inform the review board about the planned changes and wait for OK to proceed.
Document and communicate the metamodel changes
- Document the planned changes in the PCM Changelog
- What entities are new, what relations are new, what was renamed?
- What was the design rationale of the changes?
- Which entities changed semantics?
- For semantic changes of existing concepts: Provide a guide how to migrate from the old to the new concept (e.g. how to query previously existing information after changes)
- Document the changes in the SVN commit log message
- To ensure traceability, do not commit anything else, when committing to pcm.ecore
- Document the changed model elements in the metamodel
- Every package and meta-class must have documentation
- Furthermore, document the most-important associations (i.e. the same meta-class is associated via two different associations OR the names of meta-class and association deviate OR complex concepts represented via association)
- Except for minor changes (see below), the changes should be communicated to the other developers. Use the sdq-dev mailing list or the Palladio Concall for this.
Generating code based on the metamodel changes
Before performing metamodel changes, check with the PCM Strategist (Stephan Seifermann) if there are reasons why the changes should be deferred. Reasons include:
- a release is pending (a feature freeze is in place)
- some tooling might not be adapted in time to metamodel changes because necessary developers are not available
- some development (e.g. projects) is heavily depending on a working nightly build (this is considered bad style)
To generate the PCM:
- Make sure that you have the Palladio Coding Conventions activated
- File "de.uka.ipd.sdq.pcm/model/pcm.genmodel" -> context menu -> Open With -> EMF Generator
- Clean-Up Files before regeneration: (it is currently unclear, if these steps are still needed)
- Delete Directory META-INF including MANIFEST.MF
- delete the files build.properties, plugin.properties and plugin.xml
- Root node = "PalladioComponentModel" -> context menu -> generate all
- Fix dependencies in MANIFEST.MF: (it is currently unclear, if these steps are still needed)
- Add Dependency to org.antlr
- Add Dependency to de.uka.ipd.sdq.errorhandling
- Export Package de.uka.ipd.sdq.pcm.stochasticexpressions.parser
- Before committing, check the files your are about to commit. Make sure to not accidentally commit further files. Make sure the diffs are not cluttered with formatting changes (e.g., by not having the Palladio Coding Conventions properly activated)
Except for minor changes (see below), code should be regenerated urgently (i.e. within days) for the changed metamodel and the tools depending on the metamodel should be checked and adapted if necessary. Major tools to adapt are:
- Sirius editors
- OAW Templates
Developers working on their own PCM-dependent tools should fix their tools. They should know about the changes anyway, as the changes should have been announced. Performing all those steps alone is not feasible by a single person in most cases. A developer normally does not know about all tools that are currently used and how to fix them if metamodel changes break them.
For every major tooling area (editors, templates, solvers), at least one, better two or more Palladio group members should be declared that are able to fix these tools (or know whom to ask). If you plan to make changes to the PCM metamodel, get in touch with members of the Palladio development group to:
- Make sure the metamodel changes are observed
- For each tool, a SDQ group member agrees to fix eventual code breaks urgently
- A time horizon is being discussed in which an updated tool version in the nightly build can be expected
Minor metamodel changes (such as simple renames) do not necessarily imply generating all the code immediately. If you discover such metamodel changes, provide a bug entry. Such bug entries can be resolved in some kind of batch mode later.
Quality Assurance / Testing
If changes to the model would are classified as breaking or breaking and resolvable (see ), they potentially break the PCM tooling (editors, edit helpers, transformations, simulation, analysis, etc.). If changes are potentially breaking: PCM developers responsible for the maintenance of affected tools need to be informed; they need to have time to fix the tools in time.
Tooling checks after model changes:
- Regenerated code (EMF model)
- Create example systems with the fixed tools (at least minimal PCM example + all new and changed meta-model elements)
- Run a SimuLizar simulation and the PCM Solver
- Check the simulation and analysis results for plausibility
- Each major Palladio contributor has one member in the Palladio review board
- Review board members assure to answer review requests within 3 work days
- Review board members can nominate surrogates to ensure quick responses
- Current review board members are
- FZI/KIT: Misha Strittmatter
- University of Stuttgart: S. Becker
Major changes to the PCM are all changes except for renames (e.g. typos) of class names, attributes, and references.
When it comes to releasing (un)stable PCM builds, extended testing effort is necessary. Coding nights are excellent to prepare a release. Thus, we agreed on establishing a metamodel freeze at least 14 days before the release in order to allow for efficient testing and bugfixing.