Projects

The largest unit of code organization at Art+Logic is the project; as a rule, code does not get written unless it is part of a project, whether for an external client or for internal use. Every project we work on should have a certain set of common features that allow new programmers to integrate smoothly into the workflow.

Standard Directory Structure

Each project should maintain two separate directories for its documentation.

Deprecation warning: Because tags/branches aren't stored as separate directories in git, there's no reason to continue using that trunk/tags/branches convention when using git on a project.

The first standard directory is located at ClientName/ProjectName/trunk/Documents All project documentation meant for delivery to the client or end users should be maintained in this directory, and its contents should be included in releases.

The second, located at ClientName/ProjectName/trunk/AlDocs was historically reserved for internal documentation for the project. The contents of this directory should not be released to clients. Modern projects should use the project wiki instead (see below).

Internal Project Documentation

To ease the onboarding of new team members onto projects, as well as to simplify bringing dormant projects back to life, it's important that we create and maintain internal documentation specific to each project in a well-known location. Historically, this was maintained as a plain ASCII text file named ReadMe.txt located in the project's AlDocs directory. Current projects should be storing this documentation in the project's internal wiki.

This documentation should be the main source of information likely to be needed by a team member working on the project. The habit of anyone at A+L starting work on a project that's already in progress should be to check the project's source out of source control, and then read the project wiki to get oriented.

Things that should be documented here include (but should not be limited to):

    • useful overview material

    • details on 3rd party SDKs or other tools required to build the project

    • path settings used in project makefiles

    • pointers to relevant external documents (standards, RFCs, etc.)

    • pointers to internal documents (API descriptions, UML diagrams, other design documentation)

    • anything else that would be important information for a new team member joining the project mid-stream. Try to prevent conversations like:

        • New programmer: "I installed the SDK, and downloaded all the project source, but I still can't get things to link..."

          • Project manager: "Oh, of course. You need to change {a registry setting | compile option | path | wave a dead cat over your head}."

As the project grows, the project manager is responsible making sure that this documentation is maintained.

If there's documentation that should be released with the project source for the client's use but would also logically be maintained in this internal documentation, it should be maintained in a file in the project's Documents directory, and the project wiki should include a pointer to the document where that information is maintained. Don't duplicate the information between the two locations.

Release Procedure

Every project needs to have a documented, repeatable release procedure. At the very least, this procedure needs to exist as a list of steps in the project wiki that must be performed in sequence to issue a release to the client.

The preferred approach is to create an automated release procedure that implements the steps required to perform a release of the project as a separate program that performs each of the steps required to prepare the project for release to the client (or other end users of the project).

Common steps performed as part of a release procedure include:

    • retrieve current source from source control into an empty directory

    • perform a fresh build of the project

    • execute a test suite (at the very least, a rudimentary smoke test should be performed)

    • build an installer set

    • tag the version in source control

    • upload the installer set to a point where it can be deployed or delivered to the client

Version Tagging Rules

As we work our way through a project, it's important that we be able to uniquely identify each version of the project's deliverables that we release to our clients, no matter where in the lifecycle of the project we may be, or whether the deliverables in question are desktop applications, web applications, or designs or other documentation that we are working on.

To do this, we use the typical "X.Y.Z" numbering scheme with an extension (modeled after the version numbering system used by Apple) to indicate the development phase the project is currently in.

The "X.Y.Z" part of a version identifier represents the release target that our development is working toward -- for example, we may spend multiple months divided into multiple milestones working toward a 1.0.0 version of a project for our client, During that period, the release target portion of the version ID does not change, so we need additional encoding to represent the progress of our development efforts.

While we are working toward a release target in a project, we add additional development phase information to our version identifier to indicate where our development efforts stand in relation to the release that we are targeting.

Whenever we release software to our clients, either the version target or the development phase part of the project's version identifier must be incremented.

What is a release?

In the days when there were nothing but desktop applications, this question wouldn't make much sense, but it's certainly more confusing now. For our purposes, we will consider any of these events to be a release:

    • Providing an installer image for a desktop application to the client

    • Updating source/binaries on an Art+Logic-controlled staging server for feedback from the client

    • Updated code (source or binaries) being placed on a client-controlled server for use by the client's end users

    • Any other time that we're sending updated project deliverables to anyone outside of Art+Logic. This can include design mockups, documentation, use case analyses, or anything else that completes a project milestone.

In almost all cases, a release will be tied to a project management milestone for the project, and project managers should always use the version id scheme outlined here as the name of each milestone in a project.

Encoding Version Information

Release Target

By default, all Art+Logic projects start life targeting a 1.0.0 release. Frequently, clients will come to us to take over a pre-existing project that's already at some higher version identifier, and some clients like to pick version identifiers on a whim -- in those cases, we adopt whatever version number the client dictates.

The semantics of the components of the release target X.Y.Z break down as follows:

    • X: Major version number. Should be incremented only when significant changes to the application have occurred (total rewrite of the codebase, incompatibilities with previous releases). Most frequently incremented when the client's marketing department insists that it's time for a new version.

    • Y: Minor version number. Should be incremented when new features are added to the project.

    • Z: Patch level. Incremented when a release includes bug fixes or other very minor updates.

Development Phase

Because we usually need to provide our clients with multiple versions of their project while we are working toward each of the release targets, we also encode information about our development progress on each of the releases we issue to the client that are provided to them for testing and to track progress during the development process. The development phase is always provided as two pieces of information, the 'phase' (a single letter) and the 'sequence' (an integer starting at 1 for each phase).

The phase identifiers we use are:

Avoid using Alpha designators -- they really come from an era of waterfall-style development where a project is thought to begin its life with a finite set of well-defined features that we move toward in a single, long-term development campaign, and we can reach a point where the project can be said to be 'feature complete'. That's not consistent with the way our clients need us to work, and even worse, it can lead to a mindset during development where the goal of reaching that feature complete stage can give developers an incentive to declare tasks as complete when they still require a significant amount of work to make them production-ready. This syndrome is visible on projects where all the development tasks are marked as complete, but the project still remains unshippable because of a bug count that remains high as long as we work on the project. By moving to a development lifecycle where we focus on smaller chunks of work and get those pieces production-quality as soon as possible, we let our clients ship working code to their users earlier in the project and with better results.

It's rare for web applications to go through a Final release candidate phase, because of the vastly reduced expense and difficulty of changing things on a website as compared to desktop applications, where the client might need to have physical media and hardcopy documentation updated to reflect changes in the software.

Releases that are destined for a client's end users (other than beta users) should never see a piece of software that's stamped with development phase indicators.

Possible release sequences will look like:

Desktop Application

...and so on.

Web Application

...and so on.

Encoding Release Numbers in Binary Format

Several platforms (Windows and iOS in particular) require that version numbers be encoded numerically so that the operating system can determine which of two application versions is more recent.

When working on one of these platforms, that numerical version identifier should be constructed by replacing the development phase letter with a numeric value as follows:

So,

Note that this encoding should only be used where a numerical version is required; anyplace that the application displays the version as text, the text encoding should be used.

Source Control

Each release issued outside Art+Logic must be tagged in our source control system with the release's version identifier. Art+Logic version identifiers use a tag name as follows (prefixed with the word Release).

Release<major>.<minor>.<patchlevel><code><release>

For example:

Release1.1.0b1

Note that some older projects may still be using CVS instead of Subversion or git. Since CVS doesn't allow periods in tag names, we use dashes instead of periods in CVS tag names.