Service revisions
Learn the concept and steps for service revisions.
Introduction
With Uniscale, you can create revisions for each service, allowing you to compare revisions and get a historical overview of changes. Furthermore, your revisions will have their own approval flow.
In this article, we will explore two areas:
How to: Service revisions: Learn how to utilize this functionality.
Concept: Service revision: Understand the concept behind revisions.
How to: Service revisions
Service locking and approving
You will lock and approve each service revision as you want to keep track of your changes over time.
Select "Ready all"
In the overview, select "Set all to ready"
Select "Approve"
Give your revision a title. Note that it will automatically get a version number.
Optional: Add a description.
Click "Submit"
Once you have approved a revision, you can head to the SDK Portal to generate an updated SDK: Generating the SDK
Create a new revision
To start a new revision:
Click "Start new revision"
Give your revision a title. Note that it will automatically get a version number.
Optional: Add a description.
Click "Submit"
Service changelog
To view the changelog, click the "clock" icon in the upper right corner.
You can select and compare each of your revisions and get an overview of all changes.
Each color will represent the type of change:
Green: Added
Purple: Modified
Red: Deleted
Explore previous revisions
To explore each of your previous service revisions, click on the name of your revision in the upper right corner.
Concept: Service revision
Within the cycles of modeling and producing well-written documentation, you will find yourself completing items and getting them to a stage where you can lock things in place before a revision.
To do so in a better manner, we have provided each item in your documentation with its lifecycle related to its meaning.
For that, we distinguish between:
Items to be reused (endpoints, data contracts, properties).
items that are single declarations (namespaces, Use case flows, Technical use cases)
Each item is subjected to a lifecycle, with different meanings.
Completion cycle
Endpoints, data contracts, and properties are considered items that are agnostic of the entire status of the service. As a whole, they can be "completed" before the overall approval status and as such, their cycle reflects their state of being "done" or "completed".
Exploring step by step the process, we have:
When a new item is created, it is in the status of "
draft
"Afterward, with new changes done, it goes into "
edited
"Once all the conditions are met, the item can be "
completed
"Once completed, the item can be
"opened"
to new changesIf some changes are made, then the item is moved back into
"Edited"
Lockable cycle
Namespaces, technical use case flows, and use case flows are all process items that are relevant to the end goal of the service. As such, rather than a completion intention, they have a "is this final", or "is this locked" cycle.
Exploring step by step the process, we have:
When a new item is created, it has the status of
"edited"
Once all requirements are met, it can now be
"marked as ready"
When the owning module is
Approved
, all items are moved to"locked"
Later, when a new revision is made, all items are still in
"locked"
From here, one can manually
"unlock"
the items that are intended for changes, and move them to"unlocked"
If any change is made to a
"unlocked"
item, it gets automatically moved to the status"edited"
Approval of the service & revisions
Service approval is a collation of all the above processes and loops. Let's take a conceptual example of that scenario, with images to visually represent the state at all times.
In the start, the service grows to a stage where various items will be in either the
"locking lane"
or the"completion lane"
. This is further expanded with dependencies between the 2 types, in our example in a simple, upwards dependencies manner.
As things progress in the service modeling, all items are now
completed
and the process items areready to be locked.
With everything in place, the service has now been approved, and Revision 1.0 has been created. This means all items are moved to
locked
state and the others remaincompleted
.
From here on, of course, the service will grow towards a new revision, and to initiate one, the service will need to be opened, and various items will be
unlocked.
As such, all items that are downward dependencies of such items will be marked asOpened
, marking the intent to add changes. Once changes are made, the cycle goes back to step 1 in this guide.
Service timeline
Over time the service will receive many revisions, all needed incremental changes. This is expected and is a sign of an ever-growing service (in quality and overview of usage, and not primarily in size).
Last updated