How to contribute ================= **You can contribute to AF3 in several ways:** - submit a [bug report](https://af3-developer.fortiss.org/projects/af3-phoenix-release/issues) (and … even better a patch :-)) - [provide us AF3-example models](https://af3.fortiss.org/about-us/team/) - [submit showcases done with AF3](https://af3.fortiss.org/about-us/team/) - submit a [change request](https://af3-developer.fortiss.org/projects/af3-phoenix-release/issues) (and … even better the change itself :-)) - help us to [develop](https://af3-developer.fortiss.org/projects/autofocus3/wiki/New_developer_-_Step_by_step) the AF3 base platform - extend AF3 with [new plugins](https://af3-developer.fortiss.org/projects/autofocus3/wiki/New_developer_-_Step_by_step) - … or give us any [feedback](https://af3.fortiss.org/about-us/team/) (positive of negative) New developer - Step by step ============================ 1\. Get familiar with the software from the perspective of the user: - browse the AF3 website (http://af3.fortiss.org/) - run AF3, play with it - open the examples (available through the menu of AF3) - look at the help (available through the menu of AF3) 2\. It is now time to build a model on your own: - Let us study the alternating bit protocol http://en.wikipedia.org/wiki/Alternating\_bit\_protocol - Then implement an AF3 model for the sender and the receiver components for this protocol with direct communication channels between the two (in other words no message can be lost during the transmission). - After having a suitable simulation of this system, replace the direct channels with intermediate media components and implement a lossy behavior, i.e. messages can get lost during transmission. - Again, validate the proper functioning of the model by simulation. 3\. Set up AF3 development environment - Set up a development eclipse according to the Developer Installation 4\. Familiarize yourself with the [AF3 Development Workflow](Development_Workflow). There, you will learn to update your workspace, how to create and contribute changes, and how to perform code reviews. 5\. read the following code guidelines: [Checklist for code reviews](Check-list\_for\_Code\_Reviews) (you probably won’t understand everything since many things require to be familiar with the code in AF3, but still good to browse to get an idea) 6\. read the following issue reporting guidelines: [Check-list\_for\_New\_Issues](Check-list\_for\_New\_Issues) We are using the [gitlab issue tracking](https://git.fortiss.org/af3/af3/-/issues) You can quickly browse it just to get familiar with it. 7\. You will now be done with the general AF3 developer general knowledge, the following sections focus more on particular aspects of AF3. This depends on what your topic and is therefore to be advised by your supervisor. Modify a model programmatically =============================== Say you want to do: myModel.setParameter(42); Then you should actually write: ITopLevelElement modelContext = IPersistencyService.getInstance().getTopLevelElementFor(modelElement); modelContext.runAsCommand(() -> myModel.setParameter(42) )); Model Migration =============== When changing on the metamodel, it has to made sure that old models still load in AutoFOCUS3. Models cannot be loaded any more after renaming or deletion of model elements such as classes or attributes. Plugins that are part of the release have to load all models from release n also in release n+1 (backward compatibility). Therefore the AutoFOCUS3 kernel offers a `MigrationService`. Usability Checklist =================== When you implement a new story / plugin be sure to pay attention to the following issues related to usability: - is your plugin from the point of UI consistent with other existing plugins? - long operations should have a timeout / cancel option - during long operations give feedback to your users about the current state - when external tools are called, be sure to allow the user to specify a timeout - are all menus needed? how many mistakes can the users make? - warn users about mistakes early - provide a meaningful default behaviour - each view and each window should have a meaningful and specific name — e.g. “entity name - view name” — “DistancePlausibilisation Simulator” Workflow for model changes after release n ========================================== - Do not delete deprecated model elements (e.g. entire classes, but also single fields) in release n+1. - Rather, mark all concrete classes with a @`deprecated` comment (interfaces and abstract classes cannot be instantiated and may be omitted). - This causes the @`Deprecated` annotation to be added to the respective classes and field accessor methods in the generated source code. - Instructions - Open `ecore` file with *Sample Ecore Model Editor* (default editor) - *Context menu ->fortiss EMF tools ->Generate comment templates*. - Ensure that Eclipse Properties view is visible (can be opened e.g. by typing “Properties” in *Quick Access* control) - Select `GenModel` ->`documentation` node that as been created for the respective - Edit `value` properties field and change it to @`deprecated` - **Hint**: To speed up the process, you may also copy and paste the initial `GenModel` `deprecation` node. - Write an `IMigrationProvider` for your plugin that adjusts old models to the new model (e.g. remove, rename, …). See below. - Test model changes with all example models that are available in the file menu. - Update the models shipped in the `test-data` directory of the RCP plugin (can be done when all migrators required for the current release are ready). - Actual removal of deprecated metamodel elements: - After publishing the release n+1, the deprecated model elements and migration code written between release n and n+1 can be deleted. - It is advised to create an issue for release n+2 to ensure that this cleanup task is actually performed. Writing an `IMigrationProvider` ------------------------------- - Option 1: Directly implement `org.fortiss.tooling.kernel.extension.base.IMigrationProvider`. - `needMigration()` is a predicate that determines if the migrator has to be applied to a given model - `migrate()` performs the actual migration - `org.fortiss.tooling.base.utils.MigrationUtils` contains useful methods to migrate Kernel / Tooling-Base based models - Option 2: Use `org.fortiss.tooling.kernel.extension.base.RemoveDeprecatedArtifactsMigrationProviderBase` - Implement `getDeprecatedArtifacts()`, a method that returns the `Collection` of deprecated artifact types to be removed from the model. - Optionally also implement `getDeprecatedRootArtifacts()`, a method that returns the `Collection` of deprecated root artifact types (possibly empty subset of `getDeprecatedArtifacts()`) for which a comment is added to the migrated model that deprecated artifacts have been removed. - Register migration provider - Hints - Migration service initializes and starts very early, e.g. before the persistency service and the logging service. - During startup, the actual migration is triggered from the `org.fortiss.tooling.kernel.internal.storage.eclipse.EclipseResourceStorageService` (also very early in the AF3 initialization / startup phase). - For this reason, operations that are based on these services may not be used when implementing a model migrator, e.g. - Do not use `LoggingUtils` - Do not try to [acquire a model context to modify the model](Code\_FAQ) (not needed for migrators anyways)