design page table des matières idoc... · ref. : idoc-od-003 edition : 1 – revision : 0 draft...

IDOC General principles applicable to IDOC projects design

Ref. : IDOC-OD-003 Edition : 1 – Revision : 0 draft Date : 22 février 2016 Page 1/13

Page 1 sur 13

Table des matières

General principles applicable to IDOC projects design .................................................................................... 2

I. Introduction ............................................................................................................................................ 2

II. Mutualization .......................................................................................................................................... 2

Rationalization of IS organization .......................................................................................................................... 2

« State of the art » solutions uniformly deployed ............................................................................................ 2

Common architecture .............................................................................................................................................. 2

Common knowledge ................................................................................................................................................. 2

III. Automation .............................................................................................................................................. 3

Enforce automation .................................................................................................................................................. 3

Self-monitoring and self-healing automation .................................................................................................... 3

IV. Design rules ............................................................................................................................................. 3

V. Organization rules ................................................................................................................................. 4

VI. Developpement lifecyle ....................................................................................................................... 4

Environments .............................................................................................................................................................. 5

VII. Development Rules ............................................................................................................................... 8

A. Dependency managment .............................................................................................................................. 8

1. Explicitation .................................................................................................................................................. 8

2. Transportatbility ........................................................................................................................................ 8

B. Version control system ................................................................................................................................. 8

C. Methodology ...................................................................................................................................................... 9

D. Coding Rules .................................................................................................................................................... 10

VIII. Implementation rules (from development to production) ................................................. 10

IX. Troubleshooting management rules ........................................................................................... 11

X. Capacity planning rules .................................................................................................................... 12

XI. Evolution / modification request ................................................................................................. 12

XII. Product Assurance & Quality Assurance (PA&QA)................................................................. 12

XIII. References ............................................................................................................................................. 13



Page 2 sur 13

General principles applicable to IDOC projects design

I. Introduction

This document is in a Work In Progress Status

II. Mutualization The goal is to minimize projects duration (and thus cost). This will help build more accurate ser-

vices and provide room for improving overall quality. To achieve this goal, projects members must

be encouraged to always have an external look at their work and to seek:

Rationalization of IS organization

Use of standardized low-cost hardware & open-source software

o Generic hardware bricks (servers, storage, network)

o Generic core software bricks (data retrieval, data processing, web interfaces, statis-

tics, …)

Expected gain: easier redundancy implementation

« State of the art » solutions uniformly deployed

Expertise development allows task assignment depending on staff skills

Prefer known/experienced solutions to allow skills/knowledge redundancy

Expected gain: avoid the "critical individual"

Common architecture

Better service organization

Expected gain: much less errors, no duplicates, reduce time loss

Common knowledge

Don’t keep usefull knowledge hidden. Each costly experience or unusual information that

could be reused with profit later or by another people must be written down.

Don’t lost time to write unrequired documentation. Use lightweight formalism, as notes, wiki

pages, tickets.

Don’t lost time to search for a previously found solution. Put your knowledge in expected

places, common tools, set it reachable and searchable.



Page 3 sur 13

III. Automation

Enforce automation

Thinking about automation forces to have a level of abstraction, leading to a better design.

Automation leads to be explicit about process and rules, as they have to implemented and uses

without human intervention and hidden knowledge.

Use of automation helps avoid human error in day to day operation and insures coherent and

reproducible behaviour within the whole IT infrastructure.

Automation helps redistributing the ressources from low level and repetitive tasks to higher

added-value tasks.

Self-monitoring and self-healing automation

The software must be able to assess and provide evaluation of its output, and raise an alert in case

of deviation from nominal behaviour.

The software should also be able to detect specific specified situations and handle them.

IV. Design rules Always first have a look at similar projects and their implementations

KISS: Keep It Simple Stupid

Prefer modular and reusable open software

Use a layered architecture

Low dependencies between elements or modules

Software must be as asynchronous and time independent as possible

Service oriented, and guided by events

Easily configurable

Balance the data flow optimization and the difficulties of the software developement

Organize data in order to provide the seamless access, search and retrieval of information

Specification and design phases have to clearly determine:

o the requirements to be fulfilled by the S/W,

o the proposed architecture to fulfill the requirements,

o the definition of the interfaces (both for input and output flows of information),

o the proposed tests to verify the correct implementation of the design by the SW.

Avoid tunnel vision

o Envisage alternatives

o Objectivity towards its own project, ability to stepping aside



Page 4 sur 13

V. Organization rules Planning

Meetings

o action items

delays

assignee

o next meeting

VI. Developpement lifecyle

Software Developpement has to follow a lifecyle in order to build an efficient solution from the

requirements to the deployment.

The lifecycle is based upon project methodology (cf. Methodolgy chapter).

The lifecycle is explicit, defined at the beginning of the project and customized if necessary.

If no specific lifecycle is required, the default lifecycle is composed no less than the following

phases

Development

Integration

Validation

Production

Development should not be started without the following items, more or less complete depending

on the methodological approach:

A clear definition of goals,

A set of acknowledged and ascertainable requirements

A risk analysis

Development phase is dedicated to the building of the solution. It takes the requirements and user

needs as input and creates a solution to fulfill them. This phase is under a developer profil responsi-

bility and steered according the choosen methodology.

Integration phase is dedicated to the validation of seamless and coherent interaction of several

parts of the solution as a whole. Theses parts could be component-off-the-shell or results of previous

development phase. This is mainly a technical phase and be called Technical Validation



Page 5 sur 13

Validation phase is dedicated to functionalities and is steered by users. They test and validate, or

not, that their original requirements are fulfilled. This is manly a functional phase and be called func-

tional validation

Production phase is he mainspring of the project and the target of all these phases. Production

provides actual services to users defined according to requirements.

Every part of the solution is required to follow these phases from development to production. Any

failure is by default a no-go to next level until a fix is found or requirements are updated.

According to method terminology, scope and name could be slightly different.

Environments

The development life cycle is based on the definition and implementation of a very precise envi-

ronment policy.

An environment is the set of elements constituting the context of execution of a software solution

in relation to a stage of its lifecycle. This concerns the hardware part, the software part or the func-

tional aspect.

It’s required to get one environment per development phase.

Project requires by default the following environments:

Development environment

Integration environment

Validation environment

It’s possible to more according to risk analysis or requirement. You could have formation environ-

ment, pre-production environment, backup environment, …

Perimeter, requirements and criticality vary greatly depending on the environment, but they

shoud follow these rules:

Each environment should be strictly isolated from the other ones. No connection between

them must be allowed. As some of them have to be pushed to the breaking point or used at

same time with different goal or configuration, any interference should be avoided.

Each environment is designed and dedicated to reach the corresponding phase goals. Build-

ing software is very different from validating it. Use the right tool for the right stuff.



Page 6 sur 13

Each environment, except production, should be designed to be easely and quicly configura-

ble, refreshable, destroyable and replacabe with no regret. A static and precious environment

is a useless one.

The development environment

It is entirely devoted to code development, research of the best solutions and experimentation. It

must meet the needs of the developer.

No other service should depend on it because it has its own life cycle: it can be disrupted at any

time.

As far as possible, its dependence on external services should be minimised.

Ideally, the development environment is fully transportable on a laptop.

Each developer should have its own development environement and could modify or break it

without fear of side effect.

It is inherently ephemeral, versatile, degradable and refreshable.

It should be easily reproducible with a minimum of human intervention, as its interventions may

introduce discrepancies.

Dependance management system should be used. It should be automated, tooled and objec-

tivated as a file or a configuration.

It must not have any link with production data, including reading data. It must have its own rep-

resentation of the production data, either as a sample, a copy or an abstraction.

Its only output is a set of source code, configuration files, possibly technical documentation and

media type resources for presentation type developments (web, GUI interface).

Integration environment

An integration environment is a context where pieces of a solution are connected and tested to-

gether. For exemple, archive management software, presentation software, databases and collec-

tion are run together.



Page 7 sur 13

Integration environment must be isolated and distinct from production, as it may introduces un-

wanted behaviors and failures.

Nowadays, integration have to use Continus Integration Services as Jenkins, Gitlab-CI. Continuous

Integration is a automation of running several pieces of a solution with same trade-off and ab-

straction. It fires on time-based period or on each modification of source code.

As Continuous Integration actually require some trade-off, if risk analysis requires a more accu-

rate integration tests validation, a dedicated Integration should be provided.

If environment are easely and quicly configurable, refreshable, destroyable and replacabe with

no regret, validation and integration environments could be the same, but must be distinguished

in use.

Actors and goals are not the same.

Integration is built for technical people to validate technical claims.

Validation environment

This one is used to validate, in a context sufficiently similar to production, that the requested

functionalities correspond to the users' expectations.

The most important notion to define is to delimit what is being tested and what is outside, at a

given time. In a system where several elements are interacting and evolving, it is necessary to

test only one element at a time.

Due to the isolation of environments, a validation environment cannot use production data, even

in read-only mode. But the data must be sufficiently similar to the production data in terms of

representativeness.

The main actors are the representatives of the users.

The deployment managers use this phase to check that the installation and/or update procedures

are correct and consistent. In fact, depending on the size of the team, this may involve the distri-

bution of roles between the developers themselves or, on the contrary, between completely dif-

ferent people in order to maintain neutrality of point of view.

Production environment

The production environment is the goal of any development process. It is the one that renders

the service for which the project exists.



Page 8 sur 13

It has its own rules.

Similarities and differences

TBW

VII. Development Rules Using other people’s code and planning to share your own code helps save time and enforces code

quality. The sole benefit of software development is software running seamlessly

Use project management tools (redmine, gitlab)

Use a development methodology. The worst one it’s to have none.

Implementation rules (process from development to production) must be integrated in de-

velopers mind and in development codes

Code must be commented and documented (redmine)

Requirements are linked to expectations.

A. Dependency managment

1. Explicitation All dependencies must be explicit descripted.

All dependencies must be saved and managed in configuration.

There must be no dependency

To the developer (any developer must be able to continue development)

At the workstation (with the exception of developments related to hardware)

To hidden, implicit and non-standard elements

2. Transportatbility Any development must be transportable, from the source code, the usual utilities and documen-

tation, to another workstation or server.

Material loss of a workstation should not represent a risk to development.

B. Version control system

Essential elements must be saved and managed in configuration in Version control systems.

The Version Control System should be trusted, backuped and safe.



Page 9 sur 13

Be carefull by using public Version Control System as Github because of licence concerns and

mandatory French rules for public insitutions. By default project may use the IAS gitlab instance.

Source code, scripts, configuration files must be saved in a code version manager. Items that can

be obtained source code as binaries resulting of compilation should not be saved in a version con-

trol system, but in a more appropriate artifact manager.

Settings files, which are specific to a particular instance or installation, possibly containing confi-

dential information, should never be saved in a code version manager.

Do not confuse configuration and parameterization.

Configuration → assembly of beans according to a configuration

o Development, Integratio, Validation, Production

Parameterization → installation-specific properties

o Same configuration, same product, several installations

Specific parameters: DB connection, server address, company name, ...

Since security must be based on the quality of the mechanisms put in place and not on hidden

information, development must be carried out as if the whole world could access it.

It is necessary to be able to establish an unambiguous link between a source code version and a

deliverable at all times.

It is necessary to be able, at all times, to establish a link between a version of source code and all

the developments it contains.

C. Methodology

Work In Progress

A Software product and its implementation will be described by the following documents:

o Software Development Plan,

o Software Requirements specification document (SRS)

o Software Design documentation, containing the SW requirements & architecture,



Page 10 sur 13

o Software configuration file/release document

o ICD’s, describing the external and, if applicable, the internal interfaces,

o Verification and test plans, with the description of the tests to check the correct im-

plementation of the design requirements,

o Test procedures and test reports, summarizing the results of each test,

D. Coding Rules Coding rules

o Use IDE (Eclipse, PyCharm, VScode, …)

o ICI AJOUTER DEFINITION D’UN IDE

o Use version tracking (git)

Releases

Branches and merges

Validation (continuous integration)

Software testing (use cases):

o unit testing

o functional testing

o regression

o load testing

o Use issues software (bugtracking / feature request in redmine)

o No hard-coded paths or values (configuration files)

o Software compilation should raise no warning

Provide user manual containing the description of the SW, use cases, troubleshooting and

description of error/warning messages,..

It is mandatory to set up a SW repository on a stable server that is regularly backed-up.

VIII. Implementation rules (from development to production) Execution pipeline schema and redundancy

Network flows and redundancy

Monitoring

Production monitoring tool

Documentation and disaster recovery plan (redmine, wiki, …)



Page 11 sur 13

IX. Troubleshooting management rules At the time of the specification and along the life of the projet, anomalies/incident must be cate-

gorized. For each category a level reaction and a solution must be assigned.

Each incident must be thoroughly searched for causes and remedies.

The first source of the problem must be identified and the corresponding higher level remedy

determined. If unapplicable, an alternative solution must be tested and set up.

These solutions must be described and documented.

To ensure the fastest possible response, foreseen or known possible incidents must have spe-

cific incident response documents

The staff member responsible for solving the incident uses these documents to:

o Confirm the anomaly

o Check the anomaly context

o Specify the anomaly type

o Follow the anomaly resolution procedure:

o Action

o Validation of the action

o Result of the action determines the next step

If the incident response document does not solve the anomaly:

o Protective measures to implement

o Description of the anomaly impact: scope, severity

o Required competencies and support level needed to solve the anomaly

o Which project hierarchy to notify

Incident response document:

Description and meaning

How to make sure the occurring incident is the same as that described in the document

How to circumscribe the incident

Emergency contact

Description of corrective measures to apply, in order of occurrence probability

How to ensure that the situation is back to normal / that everything is operational

How to resume the interrupted processing, and how to process the elements that were

undergoing treatment when the incident occurred



Page 12 sur 13

How to report the incident

Reference document : IDOC-OD-016 IDOC Fiche incident type

X. Capacity planning rules Anticipate the changes needed in infrastructure to preserve ongoing activity with regards to ca-

pacity and load evolution

Anticipate technical evolutions and hardware/software obsolescence

XI. Evolution / modification request When modifications are needed compared to the current running software configuration, the

changes have to be planned as described hereinafter.

- Which portion of the existing software/system/network will be impacted

- Are there existing features wich will be lost ?

- Will the migration towards the new configuration be transparent?

- The need of regression testing shall be analysed.

- Authorize switching back to previous version of the software.

-

XII. Product Assurance & Quality Assurance (PA&QA) Every step above must be respected in order to meet the minimum PA&QA level.

To ensure that these requirements are followed, the project must evaluate that:

• software requirements are properly specified;

• formal definition documents are issued;

• standards, practices and conventions are applied (e.g. logic structure, coding, commentary);

• design and development activities are subjected to formal reviews;

• all verification and testing are carried out against formal test procedures written according to

the criticality of the software;

• Configuration management control procedures are applied.



Page 13 sur 13

Appendices

XIII. References ESA ECSS-Q80C

design page table des matières idoc... · ref. : idoc-od-003 edition : 1 – revision : 0 draft...

Documents