DetailedHowDoesItWork

Plugin Concepts

The idea behind the plugin is that individual Archi models (i.e. .archimate files) should be able to be managed as part of bigger repository of models so that Archi can be used in an enterprise environment as well as a personal one.

The plugin treats a given .archimate file as a coherent collection of related ArchiMate elements, relationships & diagrams, but allows for the fact that multiple people may want to work on this content at the same time so uses GIT as a mechanism for allowing the content to be shared.

Branch = Model

The plugin takes the approach that there is a one-to-one relationship between a given Archi model and a branch in GIT. This means that whenever you add your model to GIT (i.e. export it) you will be asked what branch you want to put the model on. Similarly, when you import you are asked which branch you are getting the model from.

The important aspect of this is that the list of files that are versioned to given branch in GIT should be a coherent and valid Archi model i.e. Something that can be imported into Archi and won't cause issues related to broken relationships, missing diagram elements etc. Because the plugin only lets you export and import to/from branches, if you only use the plugin you should be able to guarantee that the integrity of your model will stay intact.

Sharing, Merging & Files

The reason why the plugin breaks the model into separate files per element/relationship/diagram is to try to minimise the chance of conflicts taking place when you go to share a single model between multiple people. The files themselves contain the information about the given element/relationship/diagram written out in YAML format. Why YAML? Well, because it is a lot more readable than XML and when you are sharing models, if you do come across a conflict you want it to be easy to understand and XML is, quite frankly a nightmare to try to read in that situation.

So, how do you go about sharing a model? Here is how the plugin handles this:

• Somewhere along the way someone has created a model and versioned it to a GIT branch and pushed it up to a remote GIT repository so others can access it
• Person X (let's call him Scott) comes along and wants to modify the model. Scott uses the import function and is asked two important questions - which branch are you importing from? and which branch will you be saving to?
• The branch he is importing from is the one the original person has committed the model to. The one he is saving to - and this is the important bit - defaults to the name of the original branch appended with Scott's name (i.e. scott in this case) so that any changes he makes and commits will go on a new branch that has been forked from the one he got it from
• Now he can work independently changing, adding etc and committing his changes both locally and remotely without having to worry about conflicts
• When it comes to the point where Scott's changes need to be made part of the original model, the repository administrator (who understands about GIT merging, conflicts etc) merges Scott's changes back into the original branch, resolves any conflicts and tests the model to ensure it's integrity is intact
• If everything is OK, then the branch representing the model is updated with merged model, ready for the next round of changes

From this description hopefully it is clear that if the same people are changing the same elements, diagrams etc, then there will be merge conflicts that will need to be resolved. Therefore, the smart thing to do is to make sure that if you are sharing a model, that you have clear ownership of elements, diagrams etc so that as much as possible two people are not going to change the same thing at the same time.

In practice the biggest area where this is important is diagrams - but this should be the easiest area to make sure that ownership is clear because a given diagram will have been created by a single person and if the maintenance of the model is being properly managed, it is unlikely that two people will try to change the same diagram at the same time.

Elements are a bit different because they may (and hopefully will) be reused on multiple diagrams and therefore might end up being changed by multiple people at the same time. Model elements are significantly simpler than diagrams though, so even if there is a conflict, it should be straightforward to resolve - perhaps choosing between two different descriptions.

Model Files Are Temporary

Using this plugin, what happens is that your .archimate model files essentially become the repository for your current model, but are part of a much bigger picture. This is because once you've added the model into GIT, you can create as many new .archimate files of the same model as you want from the GIT repository. i.e. The GIT repository becomes the master for your enterprise ArchiMate model, itself made up of multiple models that you can merge and combine as you like using the tools in GIT to help you achieve this.

Maintaining Integrity

The main risk/challenge in using the plugin (in it's current form) is that you might mess up the integrity of the model through GIT merges. A couple of best practices should hopefully avoid this:

• As mentioned above, assign ownership so you don't create merge conflicts.
• If creating new branches using GIT tools that combine the content of other branches, make sure you always take all the content in a given branch that has been created directly from an plugin export. That way you know you have a whole model that has integrity. You can then import your combined models into a new model and remove elements, relationships & diagrams using Archi which will ensure the integrity stays intact.
• If you have merged branches, make sure you test the merged model in Archi - create a diagram using an element and/or relationship from different places in the model; open and modify existing diagrams etc. If you get errors then chances are you've made a mistake in your GIT merge somewhere.

Lastely, don't forget that GIT is a version control system, you can always revert to a previous version if you mess something up :)