Difference between revisions of "HowTo:Organize UBIK Development"

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^®.

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. 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.

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:

1. Requirements - before you can do anything, you must know the goal and agree on it with the customer.
2. 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.
3. 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.
4. 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".

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).

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.

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.