APPLICATIONS AND DATA SERVICES BEST PRACTICES FOR SOURCE CODE AND DOCUMENTATION REPOSITORY AND SAMPLE SET

OF ARTIFACTS

EXECUTIVE SUMMARY: Since software projects evolve over time, it is important to have a scalable strategy for organizing source code files and documents. This document is intended to be a tool to help achieve that scalability.

TABLE OF CONTENTS
PURPOSE: .......................................................................................................................................... 2 AUDIENCE: ....................................................................................................................................... 2 Guidelines: .......................................................................................................................................... 3 Documentation ............................................................................................................................... 3 Reports ............................................................................................................................................. 5 Database ........................................................................................................................................... 5 Development Code ........................................................................................................................... 5 Production Code ............................................................................................................................... 6 Vendor Code .................................................................................................................................... 6

1 of 7

Date Revised: 03/09/2007

PURPOSE: One of the IT Architecture Operating Principles drafted by Ecologys Business & Information Technology Advisory Committee (BITAC), is to use a common set of development methods. One aspect of all IT Projects is the need for a source code repository. A source code repository is a tool that allows project team members to store and manage source code files and project documentation in a central location. The purpose of this document is to outline best practices for organizing a source code repository and describes a sample set of documents that would be contained in the repository. The benefit of using a consistent source structure is that it enables project team members to maintain consistency as the project grows, and makes it easier for new contributors and maintainers to get up to speed. Users of this guideline are encouraged to incorporate those aspects that are appropriate for a project, and to supplement the guideline over time as knowledge and experience using them is gained.

AUDIENCE: The intended audience is software application developers, analysts, and project managers having an interest in how source files and documents are organized for easy retrievability.

2 of 7

Date Revised: 03/09/2007

Guidelines for High Level Structure:

Guidelines for detail structure:

Please note: Not all projects require this detail structure. Please add or remove the folders to suit your project needs.

Documentation (See Footnote at end of document) Project Management Project Authorization Document Change Management Change Plan Change Request List

Requirements/Analysis (As appropriate, these documents are updated throughout the life of the project) Current Business Process Flow Diagram Proposed Process Flow Diagram Issue Log Business Requirement Inventory Software Requirement Spec

3 of 7

Date Revised: 03/09/2007

Architecture Diagram (logical, physical) Use Cases Use Case Documents (including post release use cases) Glossary Assumptions/Constraints Design Sequence Diagram Design Model Design Class Diagram Interaction Diagram Standards and Conventions Developer Tool Configurations

Migration Data Migration Plan Data Migration Conversion Code (SQL, Programs etc) Data Migration Validation (SQL, Reports etc) Construction Build Procedure Document Testing Unit Test Scripts Functional Functional Test Plan User Acceptance Test Scripts Test Plan User Help Documentation User Help Manual Deployment

4 of 7

Date Revised: 03/09/2007

Deployment Checklist Deployment Configurations (Server Descriptions, Special Permissions etc) User Release Notes Ron/Mike Server Document Post Release Project (Contains documents created during a post production release) (Helpful Tip: All code should be labeled with the Release Number) All artifacts created (share to appropriate folder above, ie use cases) Reports (This structure is tailored to Crystal 10) Development Reports Development Report Web Pages Test Reports Test Report Web Pages Production Reports Production Report Web Pages

Database Data Model Data Dictionary Build Scripts Sql scripts for creating Database entities Operational Scripts Sql scripts for common data fixes Development Code Follow the folder structure of the current development template at the following locations: Expandable web app:
http://ecywblcyadxd0/sites/ads/eaa/Standards%20and%20Guidance/ExpandableWebApplicationProj ectStructure.doc

Self contained Web app:

http://ecywblcyadxd0/sites/ads/eaa/Standards%20and%20Guidance/SelfContainedWebApplicationP rojectStructure.doc

Release XXX (For post prod releases, this folder contains info for other developers indicating what code is affected by current change) 5 of 7 Date Revised: 03/09/2007

Document to identify code/database changes by post release number User Release Notes Production Code (It may not be necessary to have a Production Code folder if there are few differences between Test and Production) Server Folder Structure (Same as Development Code Above) Vendor Code Folder for Each Vendor Product (ie XML Parser, Microsoft JVM, InteropXXX.dlls for.net projects)

6 of 7

Date Revised: 03/09/2007

Footnote:
Often, projects evolve over time. With new iterations of a project, a new version of the product may begin while a previous version is stored in the repository. This is done in the event that the new version production is prematurely halted, so that bug fixes and enhancements can continue while the new version is developed or it is necessary to revert to an older version of code. When a new version of a product is created, the existing code base is often copied and then modified. In these circumstances it may be beneficial to break out documentation into its own project folder, called "Documentation" and branch it off by different applications and versions of those applications so that the source documents do not get buried in old projects. The following is an example of such a documentation project. Note; that the version projects could be forgone if the document file names reflect the version of the project they are describing: Documentation Application1 Version1 Requirements Analysis Project Authorization Document Current Process Flow Diagram ... Version2 ... Application 2 Version1 ... On smaller projects or projects that are less likely to have "versions" it is usually better to keep the documentation within the project as described in the Guidelines above.

Key Contributors: Kevin Barbee Mark Collins Tommy Eden EJ Jim Holmquist Eric Lindberg

Kreighan McAuliffe Balaji Narayanan Dan Saul James Webster Bernadette Williams

7 of 7

Date Revised: 03/09/2007