AO 10477
ANNEX 20 General-requirements-for-software-development
/ File name: AO_10477_ANNEXE_20_General-requirements-for-software-developmentGeneral requirements for software development
Version – 010
DOCUMENT PROPERTIES
DOCUMENT TITLE: / Software development Guidelines
FILE NAME: / General-requirements-for-software-development_v010.doc
SUBJECT: / General requirements for software development
DOCUMENT TYPE CODE: / GDL
CONTRACT & COMPANY: / PO
INTERNAL REFERENCE:
VERSION: / 010
STATUS:
DATE: / 2012-02-09
AUTHOR (Full Name): / FT
REVIEW / APPROVAL
Reviewed by: / Date:
Approved by: / Date:
CHANGE HISTORY
Version / Date / Description of action / Pages
001 / 2009-03-20 / Draft / All
010 / 2012-02-09 / FT revision / All
011 / 2012-03-15 / SM : add "mobile web usability guidelines" / 11-13
Contents
Contents
1General requirements for software development
1.1Use of existing tools
1.2Software code structure
1.3Environment specific information
1.4Application consistency
1.5Compliance with earlier decisions
1.6Documentation
1.7Acceptance
1.8Deadlines
1.9Versioning information
1.9.1Release versioning
1.9.2Applications with a command line interface
1.9.3Web applications
2General application requirements
2.1User navigation
2.2User input
2.3System error messages
2.4Logging
2.4.1Applications or parts of applications without Web interface
2.4.2Web applications
3Mobile Web Usability guidelines
3.1Accessing the mobile site
3.2What to include in your mobile site
3.3Navigation; Carousels; Menus
3.4Page Layout and Content
3.5Input
3.6Login and Registration
3.7Forms
3.8Touch Targets
3.9Lists, Sorting and Filtering
3.10Errors
3.11Conservative use of resources (both web and mobile)
1General requirements for software development
1.1Use of existing tools
For development, the use of appropriate existing tools is generally supported. Specifically, open source software should be used where possible. The set of tools in use must be kept to a minimum. The tools / external libraries / external dependencies that have to remain available to the software after development is completed must be approved in writing. Those must be compliant with the DIGIT hosting requirement and/or with the OP hosting requirement.Developments must allow the operational team to operate only one instance of the product chosen, i.e. a particular tool should not be used in different ways and/or configurations.This is to avoid unnecessary complexity at maintenance level. The product developed must comply with IPG rules if applicable and with DIGIT and/or OP hosting requirements. Those requirements are deemed to be known by the contractor.
As such, any use of 3rd party tools including their configuration must be carefully described by the contractor for explicit prior approval by the Project Officer.
Generally, modifications to existing tools are not desired. However, in many cases for the sake of a neat integration into the system such modifications might be the only or best approach to follow but will have to be carefully balanced, reported to and approved by the Project Officer before delivery.
For acceptance, the commonly agreed Functional Specifications count (based on the consolidated user requirements). If the contractor proposes to base the solution on an existing tool to implement these, he has to be aware of the side effects. PO is counting on the skillful approach in employing 3rd party tools in the most efficient way, yet respecting the requirements. It is clear that if changes have to be applied such should respect the philosophy of the tool chosen.
Exact details about 3rd party tools required for operation must be provided in the documentation.
1.2Software code structure
Software must be developed following object oriented principles of encapsulation, abstraction and code reusability. Future changes to a particular functionality developed in this context will be paid only as per the individual instance of change according to its single-instance complexity. This has to be taken into account from the very beginning in the software design.
Note: additional implementation and regression testing effort stemming from implementations not following this principle cannot be charged. Example: a HTML parsing logic will in future have to be refined to cover more cases. The change will be paid according to the complexity of logic involved to modify one instance of HTML parser. If the contractor chose to replicate such code or logic in more than one instance, it is expected that all instances behave consistently in the exact same way. Also new releases of a given piece of software must neatly integrate into existing software which includes that the overall behavior is consistent.
It is strongly suggested to avoid such a replication approach (more than one instance of the same code or logic). However it cannot be excluded that such approach might be necessary in specific cases. In such case the Project Officer must approve the technical approach before the release. If no such approval was given it is considered that a solution with one instance of a particular code was feasible and hence implemented and subsequent decisions made accordingly.
Initializations in the code must be done with values equal to the name of the variable when possible (i.e. username = "username").
The code must be clearly commented to allow an external reviewer, not member of the development team, to understand its purpose. This includes an overall comment for each file plus a specific comment for each method, variable or set of variables, imported methods or variables…
Comment such as "Transforms the added objects" for file TransformWebScript.java is not sufficient.
If a section of code is set into comments, associated comments should be clearly noted as no more valid (for example with the mention KEPT FOR HISTORICAL REASONS) and the valid comments should be consistent with the valid code.
The code also includes script files, configuration files (including configuration files for development tools), code files, libraries used by the software and necessary to compile a release or build it. The PO must have all data, with any delivery, to re-compile and re-build the release by its own.
The source code delivered for each release must be a full extract of the code valid for the current version of the software and should not be limited to a part of code only used for example to create a corrective minor release.
Similarly, the code must be designed from the beginning to be multilingual, ie no message shall be hard coded. All text appearing in the software must be clearly grouped at one place for translation purposes. If additional languages cannot be added by a simple extra configuration file (flat text or similarly easy to manipulate), the contractor will deliver at no extra cost the necessary tool to add any further language.
1.3Environment specific information
Under no circumstances software must include hard coded information about specific settings in the run time environment (e.g. file paths, IP addresses, e-mail addresses, host names). If such information is needed it must be configurable in one place only. It must be avoided that across the entire service the same information needs to be configured in more than one place.
Software code including elements as described here, is always considered a script, and may only be accepted as valid delivery or as part of a delivery if beforehand approved by the Project Officer. Software developed by the Contractor is by default always expected to be of generic use only and not contain code that binds the software to a particular instance of runtime environment. Cases where this is not possible must be brought to the attention of the Project Officer with a request for decision.
Required settings in the run time environment must be properly documented, in an understandable and usable way. Without such documentation, a delivery is not considered complete.Only documentation formally delivered and complete will be considered for acceptance.
Pre-configured settings are acceptable if they conform to the current section.
1.4Application consistency
The application must be consistent for the end user. It is the contractor's responsibility to ensure that agreements made in consolidated user requirements and specifications are followed across the entire application and overall the website service. Should this for any reason not be possible or feasible, the Project Officer must be informed before the software delivery to make a decision on how to proceed. Unapproved, inconsistent behavior of the application after its release will be considered a bug. In case of disagreement between PO and the contractor, a third party might be consulted.
Adding new features to existing software does not exempt the contractor from respecting application consistency. Should requirements be conflicting with existing features, such must be indicated to the Project Officer before release with a request for decision. Once a release is done, possible conflicts are considered bugs and as such subject to a warranty if existing.
Any online documentation (e.g. FAQ) is considered part of the application and as such must also be kept inline and consistent with the application.
Each release – even if only parts of the software have been changed – for acceptance will be treated like a complete system. Therefore, even bugs revealed but not in parts actually modified in the particular release are considered as bugs of the delivery.
1.5Compliance with earlier decisions
Any new software or release of existing software must by default comply with all previously made decisions (e.g. browser requirements). If this is not possible or feasible, the Project Officer must be explicitly informed and a decision requested before the release. Any non-indicated non-compliance will be considered a bug. If requirements are ambiguous, decisions will have to be requested from PO before the release. If requirements leave enough space to implement more than one solution, the contractor is requested to inform PO about critical options.
It is the contractor's responsibility to keep track of previously made decisions in written documents or meetings.
1.6Documentation
The following up-to-date and complete documentation must be delivered, following the PO Document Management Procedure, with every software release, unless otherwise agreed based on the nature of the project in question:
- the consolidated user requirements document, as it was approved to start the development (the requirements in this document will be also checked one by one during acceptance)
- a functional specification document
- a technical specification document
- a test report and scripts used for the testing to allow PO to re-play the tests
- a diff file that lists (based on the content and not on the date of files) the files that have changed, that are similar, that were deleted and that were added with previous delivered release.
- release notes indicating the changes since the previous version, if applicable (such document may be drawn from the relevant updated Release Management issues in JIRA or other bug tracking / CM tool and attached as document)
- manuals:
- Installation manual (including detailed prerequisites for operation if applicable, e.g. versions of 3rd party software required)
- Operation manual
- User manual
The documentation must also list all tools with their version and configuration used to develop, build and test the application to allow PO to re-do these operations by itself.
1.7Acceptance
The acceptance criteria will be the superset of requirements stemming from
- the project specific consolidated user requirement document
- the items in this document
- general rules and decisions that are in force PO wide at the time of the delivery (minimum browser requirements, file naming conventions etc)
Deliveries are tested in several areas, taking into account that depending on the characteristics of the deliverables, not all areas may apply.
1) Installation procedure: The installation procedure must reflect accurately what needs to be done to install the software and comply with OP (R4) requirements. Obviously, if it can't be installed it will be rejected.
2) Compilation:The tester must be able to recompile the code, ie the code must be complete and list all dependencies. A list of development tools with their version and specific settings must be clearly stated. If something is missing in the original delivery, it must lead to a new delivery.
3) Correct working of the software/acceptance test.
4) Guideline compliance: any departure from the guidelines will mean formal rejection.
5) Documentation accuracy: The documentation must reflect accurately what the application does or does not. Documents must also be consistent with the delivered CD content and between them. Deviation will not be accepted.
6) User requirement compliance: The application must respect the original User Requirements. However, considering those can sometimes either be vague or leave way to different interpretation, the strict non compliance does not mean rejection but re-submission, within agreed delay.
7) Test results :The tester must be able to reproduce the test results, and the reporting must be coherent. More important: if tests failed , it must be clearly documented WHY the delivery was done anyway. The test must also be relevant, and all the necessary elements must be included to be able to reproduce the tests. This includes scripts for example (Badboy, Selenium, etc).
The 5 first areas are MUST. Any failure to pass the test will mean a formal rejection of the delivery.
They are formal areas which can and must be caught by the Contractor QA.
Problems in the areas 6-7 will suspend the delivery acceptance delay until a new version is resubmitted. If the new version is not submitted within 10 days, this will mean a formal rejection of the delivery.
1.8Deadlines
Agreed deadlines must be kept. PO has no obligation to accept deliveries which are late. If due to changing priorities during the period from the agreement of the deadline until this deadline itself the agreed deadline cannot be kept, it is the contractor’s responsibility to request agreement for a new deadline before the deadline expires. It is also the contractor’s responsibility upon accepting new priorities to inform PO about the concrete changes in deadlines of ongoing projects.
Each development is accompanied by a time plan approved by the Project Officer. By default, the time plan includes a validation phase. On request, access to the development environment must be provided. When deadlines change, the time plan has to be updated accordingly for approval by the Project Officer.
1.9Versioning information
Any application delivered must provide easy means to detect its version.
1.9.1Release versioning
Any component of an application, generally named configuration item (i.e. source code, documentation, delivered zip file or CD/DVD…) must be managed through a release identified with a unique version number. Each configuration item must refer to the version number of this release. Please refer to the Release Management Inter-Lots process procedure for more details on release versioning rules.
1.9.2Applications with a command line interface
In case of command line applications, an option must be provided (suggestion –v) to display the version.
1.9.3Web applications
In case of Web applications a meta data line must be provided for every single page that makes part of this application named "version" and featuring the exact version string in the content attribute.
2General application requirements
2.1User navigation
User navigation must under all circumstances be fluid and user friendly, i.e. it must be possible to navigate to all parts of the system exclusively using clicks provided by the application. Dead-end situations must be reached under no circumstances. In Web application context, situations where navigation without browser navigation commands (e.g. BACK button) is not possible must be avoided. In cases where for example full screen preview functionality is desired, such page must be rendered in a new browser window or tab.
Wherever choices can be made or confirmation has to be given, also an option to cancel the operation must be provided. After the CANCEL the system must in all ways return to the state it was in before selecting the action to be cancelled.
2.2User input
All User input accepted by the application must be handled without error messages. By default, all user input must be accepted by the application, unless otherwise specified in the user requirements. The Project Officer may approve to restrict the application to not allow certain user input, if clearly indicated in the relevant specification documents in separate sections. A decision from the Project Officer must be explicitly requested by the contractor on such issues.
The test report document(s) must indicate all cases of user input tested. Cases not tested but found possible after release are considered as bugs and must be included in the test document(s) and used in regression testing of future versions of the software.
2.3System error messages
Any possible case resulting from the consolidated user requirements must be handled, i.e. not cause a cryptic system error message given to the user. Feedback to the user must always be given in the context of the application/service (e.g. a Web application must show its messages within the service template navigation).
Any message returned must allow the end user to figure out what wrong he has done and/or what he can do to proceed with his tasks. Any other message will be considered a bug and is a reason for rejection. In case of doubt, independent test users will be selected to evaluate the returned messages.
2.4Logging
Unless otherwise stated in the specific user requirements, all statistics typically reported to PO at the time, when the specific user requirements for the application to be developed were released, must be retrievable by the maintenance team of the application, hence carefully documented.
2.4.1Applications or parts of applications without Web interface
Logging into files must be implemented to allow operators to trace and analyze application errors in order to provide clear indications for application problems. The target file(s) for log information must be configurable. By default no other log information must be provided.
2.4.2Web applications
All information necessary for statistics gathering must be retrievable from the Web log information, i.e. the URL system must be constructed accordingly. Unless specific statistics requirements for the application in question require the presence of extra log information, no specific logging must be implemented. Any implementation of extra logging must be approved by the Project Officer.
3Mobile Web Usability guidelines
3.1Accessing the mobile site
- Detect if the user is coming from a mobile phone and redirect.
- Link from the full web site to the mobile site.
- Include the word “mobile” in the title of the mobile site.
3.2What to include in your mobile site