Difference between revisions of "HowTo:Organize UBIK Development"

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.

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

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.