When starting with a new project, you should give some thoughts to the project organization. To set up a change-friendly, clear project organization, you should take the following questions into account:
Splitting-up the project should base on logical conditions, but not on project team organization. This means: Do not create one Builder project for every team member, but e.g. one for every customer organization unit. The count of models in one Builder project is not limited technically, but more by logical reasons. At a certain amount of models in a project, it will be difficult to stay in top of things.
Additionally we recommend to collect all libraries and modules in one Builder project. These libraries and modules then can easily be reused in other Builder projects. The initial work on these libraries and modules still can be done in a specific Build project. If the library/module is ready, move it to the libraries and modules project.
This is actually an architectural decision depending on the architecture of the installation site (e.g. zone concept). In general, Base Services in a SOA context can be web services or libraries
Implementation Type | Use, when |
---|---|
Base Services |
Advantage: If the backend interface changes, Base Service interface does not necessarily need to be changed. |
Module |
|
Library |
Advantages:
|
The library version number can be set in the component diagram. Change the library version number after implementing a new requirement, that will be deployed and don't forget to document the change as described in Where to Log Changes further below.
Use major and minor versions:
Split your service into base services or libraries (also see When to use Libraries, Modules or (Base) Services above), e.g. to abstract backends.
This is useful for:
Examples:
The truth of what has been changed is only in the model! |
So, we recommend to track changes in a change log (e.g. in a note) on the use case diagram of the service model. This especially helps, if the source is located in multiple places, e.g. at the customer site and locally at the site of the project team.
Such a change log should contain at least the following information:
The Builder templates provide an default change log on the use case diagram that you simply can fill in.
Copy the lines from the change log and add them also to the check-in comment of your versioning system.
Using a version control tool to control changes of models needs some discipline. With SVN, the following approach has been proved useful:
When two ore more team members are working on the same service, it may be helpful to split the service into modules that can be worked on independently (e.g. mapping module, ...).
You should control the following files by a version control system:
If you need to rename or remove a folder that is under version control, you can
Depending on your version control system, you will probably lose history then.
We recommend to keep a service inventory in a central space, e.g. Confluence or any other wiki, operation manual (Word) or Excel list.
Make an inventory of:
Collect all specification sources (e.g. XSD, DDL, WSDL, CSV) in particular sub-folders of a folder specifications. Locate this folder inside the Builder project, if the specifications are specific to this project - locate it outside the Builder projects, if the specifications are shared by multiple projects.
After being imported to a Builder project, these sources will reside in the uml/imports folder of this specific Builder project. If sources are used in multiple Builder projects, you have to keep the import folders redundantly for each project.
You should document dependencies of imported elements in the descriptive use case diagram.
Element | Remark |
---|---|
Library |
|
Module |
|