Changes
Created page with "In this article, we aim to provide a guide and best practices for organizing the development of a {{UBIK}} project. We're going to assume that the customer's requirements wer..."
In this article, we aim to provide a guide and best practices for organizing the development of a {{UBIK}} project.
We're going to assume that the customer's requirements were already collected and use-cases have been identified.
These definitions are the basis for more detailed concepts to be developed throughout the project.
For customizing {{UBIK}}, we recommend to use the following strategy.
<!-- DO NOT REMOVE THIS -->{{Template:HowTo/Begin}}<!-- DO NOT REMOVE THIS -->
= Functional Spec & Effort Estimation =
Before working on the implementation of a {{UBIK}} project, it is essential to have a very good understanding of the effort involved. {{UBIK}} projects can be highly complex and much depends on the customer's requirements and a common agreement on a proposed solution.
For the sake of a successful project, a very clear functional specification is paramount. Without it, it is impossible to estimate the effort, and thus the costs, of a {{UBIK}} project adequately.
Also, the effort should not be underestimated; unknown factors are guaranteed to distort even the best theoretical plan into a more complex reality.
Without an adequate time frame and budget, the climate in the project will become one of stress and conflict with the customer.
We recommend PERT as a method for effort estimation.
Effort can be estimated both on task-level and on more abstract levels: For every task, three estimates are provided by the team (optimistic, most likely, and pessimistic), and for every milestone, we can calculate respective sums from the individual tasks. Then, we can use PERT for the final estimate.
= Dividing the project into tickets =
{{UBIK}} projects can be large, and it is desirable to split them into a hierarchy of smaller parts or tickets.
This makes it easier to track the overall progress and to delegate work to project engineers.
It also allows you to model the dependencies between tasks and to do them in the correct order.
Tickets can be managed with any Issue Tracking or Project Management system.
==== An Epic for every topic ====
The project should be segmented into Epics first. An Epic is a large work package corresponding to a topic or an abstract use-case.
For example, Operator Rounds (using the mobile application to do maintenance in a plant) are a classical use-case that can be managed with {{UBIK}}.
==== A Feature for every requirement ====
A use-case consists of multiple Features, i.e., functional parts or requirements for that use-case.
In the example of Operator Rounds, one such Feature could be the basic data model, or presentation of {{UBIK}} MRO work packages on the mobile client.
==== A User Story for every task group ====
Every Feature consists of one or many User Stories, i.e., groups of tasks that can be implemented within one or two weeks.
A User Story should be formulated using the following pattern:
"As a <user>, I want <requirement>, because <reason>."
E.g., or the Feature "Presentation of MRO objects on the client", we need to do different kinds of things, i.e., customize the ACM, customize the client UI, import work packages from a 3rd party system, etc. For all of those task groups, a User Story can be created to encapsulate the work.
One such User Story could be "As a maintenance worker, I want an ACM customizing for my work packages, because I want to see them on the mobile device."
Every User Story requires a definition-of-done. Those are the acceptance criteria, which can be used to decide whether the Story was done or not.
Only after review and acceptance with respect to the definition-of-done / acceptance criteria, should the User Story be considered finished.
= Requirement Supply Chain =
For every software development task, maybe even for every task in any project, but certainly in {{UBIK}} projects, there is a basic sequence of dependencies:
# '''Requirements''' - before you can do anything, you must know the goal and agree on it with the customer. There should be a definition-of-done for this task, also called "acceptance criteria" that can be defined on this level.
# '''Functional Design''' - before you can know ''how'' to do something, you need to know ''what'' to do. But the requirements aren't specific enough. You need to propose a specific behavior, look & feel, and agree on it with the customer.
# '''Technical Design''' - now that we know ''what'' to do, we need to find out ''how'' to do it. We want to do so before actually doing it to avoid frustration and reiteration. That's not always possible, sometimes we need to do prototyping in order to find out. But not to plan is to plan to fail, so a technical design should be done to the best of our ability.
# '''Implementation, Documentation and QA''' - from the previous steps, we can extract a test plan, our implementation and the documentation.
How does this the requirement supply chain fit into our tickets and project tasks?
Long story short:
You can create a user story variation for a part of the requirement supply chain, e.g. "Req./FD: Story A", and "TD/Impl.: Story A".
In the end, every story should have all requirement supply chain steps filled out over the course of its variations.
In general, we recommend adding the supply chain part(s) of a story to the title as a prefix. E.g., "Req.: Story A".
= Staging & Manual Test Plans =
{{UBIK}} projects should be developed in an environment where things can be tested, without breaking anything important.
After development, the customizing can be deployed to an integrative test environment, where the behavior under realistic circumstances and interaction with other systems can be tested.
Finally, if the customizing is considered stable, it can be deployed to the productive environment, where it will be used by the customer.
This strategy is called staging, because the functionality is going through several stages before actually being used productively.
For the migration of {{UBIK}} customizing between environments, please consider the respective [[HowTo:Transfer_Meta_Data_between_Environments|Wiki article]].
To make this staging really effective, manual test plans have to be designed and executed.
Manual test plans are basically checklists covering all use-cases, telling a tester what steps to perform in the software and what result is expected.
For every feature, there should be a test plan, consisting of as many test cases as there are use-cases for this feature.
Before any functionality is deployed to the next stage, the respective (or even all) manual test plans have to be executed.
Manual test plans backed by the customer are also a great basis for acceptance (e.g., when billing for a milestone).
= Documentation =
It is highly recommended to maintain a documentation of the following:
* Use-Cases: Provide an overview about the functional side of the project
* Data Model: Provide an overiew of the data model
* Customizing Architecture: A big picture of the customizing architecture. E.g., is there a plugin, and what does it do? Are any meta classes customized, and to do what?
* Infrastructure: Servers, URLs, safe credentials storage (e.g., KeePass), etc. for the respective environment.
** Development Environment: Infrastructure details about the dev environment.
** Integration Environment: Infrastructure details about the int environment.
** Production Environment: Infrastructure details about the prod environment.
= Code Management =
Be it plugin code or Smart Studio projects: If multiple people work on the same custom code or data model, and you have multiple delivery cycles and maybe even more than one version to support in production, then one single state of your customizing just won't be enough.
You need to track several versions of your customizing and you might even need to combine the work of multiple people.
This is possible using Version Control Systems (VCS), a.k.a Source Code Management (SCM) tools. One of them is Git.
With Git, you can develop several features at the same time, without mutual interference, because you can create a branch for every feature.
That means every branch gets a copy of what the customizing looked like at a certain point in time.
After the feature was developed in a branch, it can be merged back to what the situation looks like then.
You can look up "Git feature branch workflow" if you're interested.
Theoretially, you can use the merging capabilities of SmartStudio to do something quite similar, creating projects for every feature and merging them to your staging environments, but this approach lacks many benefits of a full-blown VCS solution.
Instead, we recommend to combine SmartStudio projects and a VCS, by working on a set of common SmartStudio projects for staging, and using VCS to control its development. It is recommended to use one SmartStudio project per topic for size and performance reasons. Optimally, you can make a clean architectural cut between the models in different projects.
If you don't use a VCS, it is recommended to create one SmartStudio project extra for every feature, and to merge them separately to each staging environment.
If you use a VCS like Git, it is recommended to apply the Feature Branch Workflow and use common SmartStudio projects for the same topics. Multiple projects in this case are only necessary to avoid too large projects that would slow down SmartStudio and consume a lot of working memory.
<!-- DO NOT REMOVE THIS -->{{Template:HowTo/End}}<!-- DO NOT REMOVE THIS -->
==See also==
* [[HowTo:Transfer_Meta_Data_between_Environments]]
[[Category:How-To|Organize UBIK Development]]
[[Category:Best Practices (internal)|Organize UBIK Development]]
[[Category:Resources (internal)|Organize UBIK Development]]
We're going to assume that the customer's requirements were already collected and use-cases have been identified.
These definitions are the basis for more detailed concepts to be developed throughout the project.
For customizing {{UBIK}}, we recommend to use the following strategy.
<!-- DO NOT REMOVE THIS -->{{Template:HowTo/Begin}}<!-- DO NOT REMOVE THIS -->
= Functional Spec & Effort Estimation =
Before working on the implementation of a {{UBIK}} project, it is essential to have a very good understanding of the effort involved. {{UBIK}} projects can be highly complex and much depends on the customer's requirements and a common agreement on a proposed solution.
For the sake of a successful project, a very clear functional specification is paramount. Without it, it is impossible to estimate the effort, and thus the costs, of a {{UBIK}} project adequately.
Also, the effort should not be underestimated; unknown factors are guaranteed to distort even the best theoretical plan into a more complex reality.
Without an adequate time frame and budget, the climate in the project will become one of stress and conflict with the customer.
We recommend PERT as a method for effort estimation.
Effort can be estimated both on task-level and on more abstract levels: For every task, three estimates are provided by the team (optimistic, most likely, and pessimistic), and for every milestone, we can calculate respective sums from the individual tasks. Then, we can use PERT for the final estimate.
= Dividing the project into tickets =
{{UBIK}} projects can be large, and it is desirable to split them into a hierarchy of smaller parts or tickets.
This makes it easier to track the overall progress and to delegate work to project engineers.
It also allows you to model the dependencies between tasks and to do them in the correct order.
Tickets can be managed with any Issue Tracking or Project Management system.
==== An Epic for every topic ====
The project should be segmented into Epics first. An Epic is a large work package corresponding to a topic or an abstract use-case.
For example, Operator Rounds (using the mobile application to do maintenance in a plant) are a classical use-case that can be managed with {{UBIK}}.
==== A Feature for every requirement ====
A use-case consists of multiple Features, i.e., functional parts or requirements for that use-case.
In the example of Operator Rounds, one such Feature could be the basic data model, or presentation of {{UBIK}} MRO work packages on the mobile client.
==== A User Story for every task group ====
Every Feature consists of one or many User Stories, i.e., groups of tasks that can be implemented within one or two weeks.
A User Story should be formulated using the following pattern:
"As a <user>, I want <requirement>, because <reason>."
E.g., or the Feature "Presentation of MRO objects on the client", we need to do different kinds of things, i.e., customize the ACM, customize the client UI, import work packages from a 3rd party system, etc. For all of those task groups, a User Story can be created to encapsulate the work.
One such User Story could be "As a maintenance worker, I want an ACM customizing for my work packages, because I want to see them on the mobile device."
Every User Story requires a definition-of-done. Those are the acceptance criteria, which can be used to decide whether the Story was done or not.
Only after review and acceptance with respect to the definition-of-done / acceptance criteria, should the User Story be considered finished.
= Requirement Supply Chain =
For every software development task, maybe even for every task in any project, but certainly in {{UBIK}} projects, there is a basic sequence of dependencies:
# '''Requirements''' - before you can do anything, you must know the goal and agree on it with the customer. There should be a definition-of-done for this task, also called "acceptance criteria" that can be defined on this level.
# '''Functional Design''' - before you can know ''how'' to do something, you need to know ''what'' to do. But the requirements aren't specific enough. You need to propose a specific behavior, look & feel, and agree on it with the customer.
# '''Technical Design''' - now that we know ''what'' to do, we need to find out ''how'' to do it. We want to do so before actually doing it to avoid frustration and reiteration. That's not always possible, sometimes we need to do prototyping in order to find out. But not to plan is to plan to fail, so a technical design should be done to the best of our ability.
# '''Implementation, Documentation and QA''' - from the previous steps, we can extract a test plan, our implementation and the documentation.
How does this the requirement supply chain fit into our tickets and project tasks?
Long story short:
You can create a user story variation for a part of the requirement supply chain, e.g. "Req./FD: Story A", and "TD/Impl.: Story A".
In the end, every story should have all requirement supply chain steps filled out over the course of its variations.
In general, we recommend adding the supply chain part(s) of a story to the title as a prefix. E.g., "Req.: Story A".
= Staging & Manual Test Plans =
{{UBIK}} projects should be developed in an environment where things can be tested, without breaking anything important.
After development, the customizing can be deployed to an integrative test environment, where the behavior under realistic circumstances and interaction with other systems can be tested.
Finally, if the customizing is considered stable, it can be deployed to the productive environment, where it will be used by the customer.
This strategy is called staging, because the functionality is going through several stages before actually being used productively.
For the migration of {{UBIK}} customizing between environments, please consider the respective [[HowTo:Transfer_Meta_Data_between_Environments|Wiki article]].
To make this staging really effective, manual test plans have to be designed and executed.
Manual test plans are basically checklists covering all use-cases, telling a tester what steps to perform in the software and what result is expected.
For every feature, there should be a test plan, consisting of as many test cases as there are use-cases for this feature.
Before any functionality is deployed to the next stage, the respective (or even all) manual test plans have to be executed.
Manual test plans backed by the customer are also a great basis for acceptance (e.g., when billing for a milestone).
= Documentation =
It is highly recommended to maintain a documentation of the following:
* Use-Cases: Provide an overview about the functional side of the project
* Data Model: Provide an overiew of the data model
* Customizing Architecture: A big picture of the customizing architecture. E.g., is there a plugin, and what does it do? Are any meta classes customized, and to do what?
* Infrastructure: Servers, URLs, safe credentials storage (e.g., KeePass), etc. for the respective environment.
** Development Environment: Infrastructure details about the dev environment.
** Integration Environment: Infrastructure details about the int environment.
** Production Environment: Infrastructure details about the prod environment.
= Code Management =
Be it plugin code or Smart Studio projects: If multiple people work on the same custom code or data model, and you have multiple delivery cycles and maybe even more than one version to support in production, then one single state of your customizing just won't be enough.
You need to track several versions of your customizing and you might even need to combine the work of multiple people.
This is possible using Version Control Systems (VCS), a.k.a Source Code Management (SCM) tools. One of them is Git.
With Git, you can develop several features at the same time, without mutual interference, because you can create a branch for every feature.
That means every branch gets a copy of what the customizing looked like at a certain point in time.
After the feature was developed in a branch, it can be merged back to what the situation looks like then.
You can look up "Git feature branch workflow" if you're interested.
Theoretially, you can use the merging capabilities of SmartStudio to do something quite similar, creating projects for every feature and merging them to your staging environments, but this approach lacks many benefits of a full-blown VCS solution.
Instead, we recommend to combine SmartStudio projects and a VCS, by working on a set of common SmartStudio projects for staging, and using VCS to control its development. It is recommended to use one SmartStudio project per topic for size and performance reasons. Optimally, you can make a clean architectural cut between the models in different projects.
If you don't use a VCS, it is recommended to create one SmartStudio project extra for every feature, and to merge them separately to each staging environment.
If you use a VCS like Git, it is recommended to apply the Feature Branch Workflow and use common SmartStudio projects for the same topics. Multiple projects in this case are only necessary to avoid too large projects that would slow down SmartStudio and consume a lot of working memory.
<!-- DO NOT REMOVE THIS -->{{Template:HowTo/End}}<!-- DO NOT REMOVE THIS -->
==See also==
* [[HowTo:Transfer_Meta_Data_between_Environments]]
[[Category:How-To|Organize UBIK Development]]
[[Category:Best Practices (internal)|Organize UBIK Development]]
[[Category:Resources (internal)|Organize UBIK Development]]
