Difference between revisions of "HowTo:Organize UBIK Development"

Revision as of 17:02, 10 November 2023

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.

[edit]

Project Structure Plan
Functional Spec & Effort Estimation
Requirement Supply Chain
Staging & Manual Test Plans
Documentation
Code Management

Project Structure Plan

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 relations between tasks and to plan them chronologically, taking dependencies into account. The result is called a Project Structure Plan, and it should be possible to reflect it on a Gantt chart. 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^®. However, for the sake of project management, it makes sense to make sure Epics have a limited temporal scope as well. This means that they should be doable within a short period in time. The benefit of this is that you can collect moments of success more frequently, and you can sell those to the customer, too. For example, you could divide the Operator Rounds Epic into two stages, Operator Rounds I and Operator Rounds II. Further, you can try to create elementary work packages that do not have any dependency in the middle, but only as a whole. This way you can avoid an Epic being blocked in the middle of its implementation, making it easier to deal with if it is blocked. Also, this proceeding allows you to model dependencies more clearly and plan accordingly.

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. The main idea of a Feature is to create a work package on a level I can still discuss with the customer, because it is not too technical or detailed.

A User Story for every task group

Every Feature consists of one or many User Stories. A User Story is a task that can be implemented within one or two weeks (it can be split up in sub-tasks if necessary). While this is the perfect scope for a project engineer to implement, it might be too technical to discuss with the customer, and that's okay, because we have the Feature for that.

A User Story should be formulated using the following pattern: "As a <user>, I want <requirement>, because <reason>." This can be also reflected in the Feature ticket, mostly.

For most features, we need to do several steps:

Find out the requirements
Make a functional design (FD)
Make a technical design (TD)
Do the implementation and testing

Hence, for the Feature "Presentation of MRO objects on the client", there could be multiple successive stories like:

Req/FD: MRO on the client
TD: MRO on the client
Impl.: ACM and Views for MRO on the client
Impl.: Client UI customizing for work packages

All of them are rather technical, but all are necessary to implement the Feature.

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. One of these acceptance criteria should always be the peer review, i.e., going over the results with a colleague to check for completeness and optimization on a constructive basis.

Only after review and acceptance with respect to the definition-of-done / acceptance criteria, should the User Story be considered finished.

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.

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.
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 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
Architecture: A big picture of the customizing architecture.
- Top-level topology: E.g., are there multiple sites? What products and client applications are used? Are there interfaces to other systems?
- Custom code: 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.

@@ Line 43: / Line 43: @@
 A User Story should be formulated using the following pattern:
 "As a <user>, I want <requirement>, because <reason>."
+This can be also reflected in the Feature ticket, mostly.
-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.
+For most features, we need to do several steps:
+* Find out the requirements
+* Make a functional design (FD)
+* Make a technical design (TD)
+* Do the implementation and testing
-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."
+Hence, for the Feature "Presentation of MRO objects on the client", there could be multiple successive stories like:
+* Req/FD: MRO on the client
+* TD: MRO on the client
+* Impl.: ACM and Views for MRO on the client
+* Impl.: Client UI customizing for work packages
+All of them are rather technical, but all are necessary to implement the Feature.
 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. One of these acceptance criteria should always be the peer review, i.e., going over the results with a colleague to check for completeness and optimization on a constructive basis.