Chapter 2 - Envisioning Your Build Migration Project

  • Article
On This Page

Introduction and Goals Introduction and Goals
Setting Up a Build Migration Team Setting Up a Build Migration Team
Defining the Project Structure Defining the Project Structure
Defining the Business Goals Defining the Business Goals
Assessing the Current Situation Assessing the Current Situation
Creating a Vision and Defining the Project Scope Creating a Vision and Defining the Project Scope
Defining High-Level Requirements and User Profiles Defining High-Level Requirements and User Profiles
Developing the Solution Concept Developing the Solution Concept
Assessing Project Risks Assessing Project Risks
Summary Summary

Introduction and Goals

This chapter provides the background and technical information required to complete the first phase of a UNIX build system migration project. The Envisioning Phase is an early form of planning, and its primary goals are to create a high-level view of the project's goals and constraints and for the business and IT to agree on them. Although IT projects can originate from either the IT organization or the business it serves, the impetus for a migration project will likely come from the business. A solution that meets the needs of the business starts with a definition of the business opportunity or problem that the solution is expected to address. The next step is to describe the desired future state of the customer's environment. This description (the vision) may be crafted by the project team or handed down by the business and negotiated as needed, and it is documented in a vision/scope document. Business and IT have to agree on that vision/scope document to go ahead with the project. Basically, the vision is what your group wants to achieve, and the scope narrows the project to what can be accomplished in this project.

In this phase of a project, a Program Manager (PM) is appointed to manage it and to organize a core project team. Members join the project and each of them helps to understand the problem in more detail and to articulate the vision. They define business requirements, identify user requirements (determined by the various roles within the organization that will use the technology), and assess the current situation of the business with respect to the technology being considered.

Using this detailed information, the team develops a solution concept, which is a high-level description of how the solution will solve the business problem. The solution concept describes the approaches needed to build and deliver the solution, and it documents business and design goals, functionality, assumptions, and constraints. It also defines the success criteria for the project, which helps the team establish the scope — the parts of the vision that will be accomplished in the current effort. Both the solution concept and the scope are incorporated into the vision/scope document.

For example, a complete Visual Studio build system may be desired — that's the vision — but the first delivery date is too soon to allow that; that concept for a solution would be out of scope. A make migration might be faster — so the scope changes the solution concept. A complete Windows build system might still be planned for a later release, however. All of this information would go into the vision/scope document.

Finally, the team makes an initial risk assessment in which it seeks to identify and qualify the various risks that the project faces. The team documents these risks in a risk assessment document.

The first phase of the project ends with a milestone, Vision/Scope Approved. To meet the milestone, the customer (business sponsor), the major stakeholders, and the project team members must accept the vision/scope document (usually in a formal meeting) as a statement of the proposed solution and how it will address the business problems. Meeting the milestone also signifies that a project team has been established and risks have been assessed. At the end of the Envisioning Phase, the business and IT should have a clear idea of the goals for the project and the project team can begin to make specific plans for how to achieve them. For specific guidance on how to organize the team and its work, such as writing the vision/scope document, building a solution concept, and determining project risks, see the UNIX Migration Project Guide.

As stated in the "Introduction" chapter, in terms of a software build system for a UNIX migration project, the Envisioning Phase contains a critical decision: whether to migrate the command line make-based build system from UNIX or to create a new GUI-based build system on Windows. This decision affects the entire migration.

Table 2.1 can be used as a checklist of the major tasks necessary to accomplish the goals for the Envisioning Phase. The technical information contained in this chapter constitutes the relevant information needed to accomplish these tasks for a UNIX build migration project.

Table 2.1 Major Task Checklist

Task

Set up a build migration team — who will do the work?

Define the project structure — how will the team members handle the work?

Define the business goals — what are the priorities?

Assess the current situation — identify the current and desired technological and business state of the development infrastructure.

Create the vision and define the scope for the project — what is the desired outcome of the project, and what could potentially restrict this outcome?

Define high-level requirements and user profiles — what is essential to the migration and who will use the new system?

Develop the solution concept — which migration strategy will the team adopt?

Assess project risks — what can go wrong and what will the project's team members do if it does?

The information in the following sections describes each of these tasks in detail.

Alternatives for a low-process, low-overhead approach are also described.

Setting Up a Build Migration Team

The first step is to assign responsibility for the build migration, which involves creating a build migration team. The team may be a distinct entity with its own membership, or it may be a virtual team within the application migration. The technical details of the migration are similar in both cases. What differs between the two is the infrastructure, including the project administration, testing, documentation, and deployment.

In the "distinct entity" scenario, the migration is the responsibility of the IT department; in the "virtual team" scenario, it is the responsibility of the application developer. Some combination of these scenarios is possible, of course, but describing the two ends of the continuum is intended to help you decide how to assign responsibility for the build migration.

The differences between these two poles may mirror how your organization handles applications themselves: a single group may be responsible for building and administering all applications, or each team may handle its own applications. The following sections discuss the differences between the two infrastructure models, and how these differences may affect your build migration.

Give Responsibility to a Single Group (Distinct Entity Scenario)

This approach is typical of a large organization with many different groups or departments that each build their own tools and applications. A single group, typically the IT department, is responsible for determining the best migration strategy for an organization's applications and for providing a consistent methodology and set of tools, as well as system support for all application migrations. They also provide the tools required to migrate the build construction process.

Having a separate team migrate the construction process is the optimal approach under the following conditions:

  • Multiple teams are migrating multiple applications.

  • The organization requires a consistent process among all the teams.

  • A single group controls the construction processes.

  • Aspects of the migration are already being subdivided among teams (libraries to one team, applications to another, and so on).

  • The migration strategy is already determined for multiple projects or groups.

Distribute Responsibility Among Developers (Virtual Team Scenario)

In this scenario, few departments are involved in the UNIX application migration, so each group migrates both its own application and its build process.

The advantages of this scenario are, first, that the developers of the build/construction process are also the end users and the customer and, second, that the interdependency of the application and the build system are easily visible. The disadvantage is duplication of work if more than one group is doing a migration.

The virtual team scenario is a good choice under the following conditions:

  • Only one application or one source tree is being migrated.

  • The migration project is relatively small.

  • The build process need not be consistent between groups, or your teams are starting with a set of makefiles that are already consistent.

  • The application development and construction teams are geographically distributed (multiple sites)

Define Who Builds the Build Process

Any development project has a number of functions that have to be performed, such as scheduling, developing, testing, user advocacy, and releasing the product at the end of the project. These functions may be performed by a single person, a small group, or a large team.

If the responsibility for developing the build process is assigned to a separate group (the distinct entity scenario), then the build migration is treated like a separate project and the build migration team will have its own people responsible for these functions.

If the responsibility for developing the build process is assigned to the developers doing the application migration (the virtual team scenario), then the build migration team shares with the application migration project some or all of the people who are already assigned to these functions and responsibilities for that project.

These functions are organized as project team roles. Roles represent a way to divide responsibilities for all of the things that need to be done in a project to ensure its success. In the following list of project roles, the work is divided based on the different skill sets needed. The list explains possible overlaps in membership between the application migration and build migration teams. It is not recommended to have a team smaller than three persons because of the inherent conflicts between the goals of some roles. Very small projects, however, may assign only one or two people to all of these roles. They should keep in mind the need to balance the goals of the different roles.

Product Management Role (satisfies customers)

This role advocates for the customer. It is usually filled by the same person who advocates for the customer in the application migration. One challenge is that the customers for the build system are not the customers for the application: customer satisfaction for the build system means satisfying the developers who must build the application rather than its end-users.

Program Management Role (delivers the solution within project constraints)

This role manages the project and the solution architecture functions, and thus requires good organization skills and software development knowledge. The person assigned this role works closely with the person assigned the same role for the application migration project to coordinate project plans and schedules (or it may be the same person on both teams if the projects are small or occurs within the virtual team scenario). One challenge to be managed is that the deadlines for the construction migration will precede those of the application migration because the migrated application cannot be tested and released if it cannot be built. Completion of the build system migration will need to be defined as one of a set of milestones in the larger migration.

Development Role (builds according to specifications)

This role is responsible for migrating and developing the build process. The developer (or developers) must understand the technical details of software construction, such as compiler details, linker details, and application dependencies upon external libraries. They must also understand software programming concepts such as multi-threading, and they must have expertise in Windows architecture and Windows program construction. It is critical that one or more developers understand the current build system and how each of the possible Windows solutions works.

Test Role (approves for release only after all solution quality issues are identified and addressed)

This role is responsible for generating realistic application build scenarios to test the validity of the migrated build construction tools. Testing a build system is a difficult task. It requires a baseline of builds and close attention to the effects of changes on the final deliverable. In some senses, the application itself is the final test of the build system. In general, the test team needs to confirm the validity of the individual tools, the instructions given to these tools, and their interaction.

It is possible to extend the idea of testing the build system to include performance measures and ease-of-use issues. Performance issues may appear in any migration.

Release Management Role (achieves smooth deployment and ongoing operations)

This role is responsible for releasing the build system to developers and groups inside the organization. Deployment of the build system is usually easier than the deployment of the application itself. The delivery dates for the build system release, as mentioned previously, are earlier than those for the software construction process.

User Experience Role (enhances user effectiveness)

This role represents the needs of the user; for a build system migration, the user is a developer using the build system. This role is responsible for the documentation that explains how the build process affects users. Much of the documentation work will be describing how the builds will be done on Windows. The User Experience Role can be taken on by a developer, although not the developer or developers of the build system itself. (A developer of any system designs the system to suit his or her needs, and not necessarily those of the end user; having someone else perform the User Experience Role is a quality check on the decisions made.) In the virtual team scenario, it is acceptable to assign this role to the developer who is migrating the build system, but it is better to assign a different person.

Defining the Project Structure

The project can be structured according to the guidance in the UNIX Migration Project Guide. The team members that represent the Product Management Role and the Program Management Role should agree on whether the build system migration is a separate project or if it is part of the application migration.

For a small, one- or two-person team, it can be enough to declare that the project will follow organizational standards. Larger teams require explicit guidelines.

Documentation standards for the build system follow internal documentation guidelines. It is possible — though not necessary — that these are different from some of the standards set for the application migration, which may apply to users outside the organization.

Change and source control are strongly recommended for the source content of the build migration. The build information is a significant part of the final product because it controls the shape of the product and how it is created from source. The change and source control policies should be the same as for the application migration project.

Issue tracking and process workflow tools are also recommended for use during the build process migration. These tools should be consistent with the tools and processes used for the application migration project.

Defining the Business Goals

The business goals for the build system usually closely overlap with the business goals for the application, but they will have some goals specific to build migration, and these goals may even conflict with the application goals. Although the goals may seem obvious, it is a good idea to clarify and document them in order to reconcile conflicts and establish priorities that will guide any trade-off decisions you need to make, both now and later in the project.

The build system may include some or all of the following business goals:

  • Minimize the time to build.

  • Minimize the developer effort for migration.

  • Ease the transition for the developers.

  • Use existing development staff and skill sets without requiring retraining

  • Minimize the risk to stability by minimizing changes to system.

  • Maximize file reuse.

  • Preserve multi-platform portability.

  • Minimize migration cost.

  • Reduce the exposure of the organization to the risk of being unable to use the software construction process in the case of personnel turnover.

  • Reduce complexity of IT maintenance agreements by minimizing the number of third-party applications used in software builds.

  • Integrate with application migration project (that is, use the same environment).

  • Maintain backward compatibility with UNIX build process.

  • Replace old construction process with something more robust.

For minimum overhead, select the top three from the preceding list and prioritize them. The Program Management Role needs to agree with the priorities.

Assessing the Current Situation

Assessing your current situation is an important step that must be taken before you attempt to create your project vision and scope.

Given that a build system migration is just one part of a larger application migration project, it is important that the assessments of the build system migration and the application development migration be done in conjunction because they usually share similar requirements, and the choices made for one usually affect the other.

The assessment you perform on your build system will help you create the scope and vision of your build system migration project. In particular, the goal of the assessment is to determine which strategy of build migration you should adopt: a migration based on the make utility and makefiles or to re-create the build system based on a new design that fits better with the tools you anticipate using on Windows.

Your assessment looks not only at technical issues and requirements, but also at business issues and requirements. You need to analyze your anticipated organizational infrastructure changes that are directly related to your move from UNIX to Windows. Any of these issues or any of the results from these changes may dictate which strategy you should adopt.

One type of assessment involves an evaluation of the current system's usability and functionality. This can be done by soliciting comments from developers and production staff. These comments should be collected and prioritized to yield a list of requirements for your solution. This assessment serves as a subjective value judgment of the current system. Obviously, it is not a good idea to migrate a build system that users think is error-prone, fragile, and requires extensive maintenance.

Another type of assessment involves performing a cursory examination of the build system to produce a high-level overview and determine some of its fundamental requirements. You will want to know who uses it, how they use it, and what applications it creates. This type of assessment serves as an objective analysis of the current build system. The following list suggests specific questions that should be answered during your examination:

  • What are the top-level drivers (makefiles, shell scripts, or another application)?

  • What variations of the final application can be built? For example, will there be a debug version, a retail version, or a demo product version?

  • How is the application and build tools source code organized, including the directory hierarchy?

  • How are makefiles distributed throughout directories? Is there a single makefile that uses include directives or recursive make invocations?

  • Does the build system handle source code versioning?

  • Does the build system handle product and application versioning?

  • If developers override features in the standard build system, how do they perform these actions?

  • How do developers modify and control existing makefiles and build information when they need to change it?

  • Are there environment variables set when invoking the system?

  • How big is the build system? Does it consist of many files or a few? Is it complex?

The assessment of your current build system should only be as in-depth and as technical as necessary to formulate your vision and define your scope. The amount of assessment may be influenced by existing or pending business and application development decisions that can dictate a particular solution, or at least indicate which solution seems better. For example, perhaps the existing build system is currently unsatisfactory or inadequate and a new design is mandated. In this case, no build system technical assessment is required at this time. Or perhaps some unresolved questions from the application development assessment exist such that a narrowly focused investigation into the build system may provide an answer. Or perhaps many of the application development decisions cannot be completed until a thorough analysis is performed on the build system, in which case a thorough technical build system assessment is required.

The details of an in-depth technical build system assessment are discussed in the "Assessing your Existing Build System" section in Chapter 3. An in-depth technical assessment is usually performed after you have decided which migration strategy is best suited for you and you can begin to plan the details of the migration. However, there are times that part or all of an in-depth assessment must be performed earlier than the Planning Phase, and this need depends on what types of questions you ask yourself as you prepare to create your project vision and scope. Some simple questions that require little in-depth analysis include:

  • Do you want to keep your make-based system?

    You may answer "yes" if this system currently works efficiently and satisfactorily for you. You may answer "no" if the developers are unhappy with it or if you are spending a lot of time and effort maintaining it and keeping it running.

  • Does the current make-based system fit into the scope and vision for the application development project?

    Your answer might be "yes" if the development environment on Windows is similar to the environment used on UNIX. Your answer could be "maybe" or "no" if the development environment on Windows is very different from UNIX (for example, if you UNIX environment is based on the command line and the future Windows solution is IDE based).

On the other hand, you may want to estimate the costs of each strategy so that they can be compared. In this case, you should ask the following question, which requires a more in-depth analysis:

  • How easily can the existing make-based system be migrated to Windows?

    Your answer to this question will be determined by the functionality your build system depends upon and whether a suitable environment on Windows can be found that provides this same functionality. To answer this question, an in-depth investigation is required into both the build system and into the suitable environments that are available on Windows.

Creating a Vision and Defining the Project Scope

With your business goals and technical requirements derived from your assessment of your current build system in mind, you can describe your ideal build system on Windows by creating a list of features and functions that you want. This process is normally done in conjunction with the application migration team.

It is almost inevitable that various business and technical constraints will require you to make some trade-offs to get a solution that works within your current business situation. A trade-off matrix can be used to help set priorities among three categories: desired features, desired schedule, and resources that will be committed to the project. For example, if schedule is critical, then some features may need to be given up to accelerate the migration. If certain features are absolute requirements, then decisions that affect other elements in the matrix must be made to accommodate them.

Decide what cannot be adjusted in the build system you envision, what is important, and what can be changed. Use those decisions to define the aspects of your ideal build system that are out of scope and will not be done. More information about using trade-off matrices is available in the UMPG.

Documenting your vision in a brief statement and specifying the scope limitations you have decided upon is the first step in creating the vision/scope document that is the primary deliverable for this phase. As mentioned earlier, the vision for the build migration needs to be compatible with that for the application migration. The scope of the build migration project will obviously be narrower than the scope of the application migration taken as a whole.

Defining High-Level Requirements and User Profiles

High-level requirements (the needs of the key stakeholders, sponsors, and end users) need to be specified to ensure that the solution for achieving the vision takes them into account. For a build system migration, the principal stakeholders are the developers and build managers who will be the end users of the build system. Some requirements may be dictated by the high-level requirements for the application migration.

The following requirements are often important for the build system and can provide a good starting point for your list. Keep in mind that, while similar to the business goals defined earlier, these requirements extend their focus to the users of the build system. The requirements may include the following:

  • Stability of build system through most stages of application development

  • Integration with application migration tools and approaches

  • Cross-platform portability

  • Backward-compatibility with the UNIX build system

  • Ease of transition for developers

  • Fast migration

  • Ability to produce a certain number of versions from a single source

  • Integration with source code control and change management tools

  • Incorporation of versioning and configuration information in the build system

After the list has been completed, the project team winnows it down to essential requirements. Some requirements may be mutually exclusive. For example, backward-compatibility may not be compatible with integration with the application migration project. In cases such as these, the project team must choose between requirements.

The User Experience Role and Product Management Role for the build migration can help the team prioritize requirements by defining usage scenarios that reveal user requirements that may otherwise be overlooked. Developers on the application migration team will be the primary end users, but the build system will also be used by or have a significant impact on the Release Management Role and Test Role on the application migration team. Usage scenarios include using the build system to build debugging versions, particular release versions, client-specific releases of the application, and to build installer packages for deployment and installation of the migrated application. For example, on UNIX, where an application is often delivered as a tar file, the creation of a deployment package is a single tar command; on Windows, the deployed package is often created using another set of commands (possibly scripts), and this may or may not be something that can be invoked from the command line. Obviously, the instructions for using the build system in either case are going to be significantly different, and new users may initially be unfamiliar with the build system. Creating usage scenarios will help you to foresee potential problems and avoid them.

Developing the Solution Concept

To develop the solution concept, the team focuses on articulating the business and design goals and constraints of the solution. In other words, the team's approach to the solution becomes more refined at this point in the project's development. As noted in earlier sections and chapters, the major decision to be made is choosing to migrate your existing makefiles by using a UNIX portability environment on Windows or to create a new build process using alternate Windows tools, such as an IDE like Visual Studio. The following paragraphs provide information that will help you better refine and articulate this decision and its implications.

The choice of strategy is a decision that needs to be shared by all of the migration teams, including the application migration teams and the build migration teams. Organizations with multiple application migrations should standardize on a single strategy for both types of migration effort (application and build system), even if the application migration teams are also migrating the build system. This makes the build system consistent across the organization and makes it easier to move developers from one team to another. It can also have benefits in the logistics of purchasing, licensing, and maintaining software tools and third party libraries.

It is possible, although very unusual, for the build migration team to select a different solution than the application migration team. This could happen when factors exist between the migration efforts that cannot be reconciled. This is not very likely because these migrations tend to have a lot in common with each other and because choosing different solutions increases the overall development complexity and the risk of incompatibilities.

Requirements and factors that tend to favor creating a new build system on Windows include:

  • Developers doing the application migration are Windows developers who are not comfortable with the command line.

  • The application migration project is doing significant restructuring and rewriting of source, such that all information captured in the current makefiles is suspect.

  • Development environment tools, such as compilers, shells, and editors that are being used for the application migration differ radically from the UNIX versions.

On the other hand, requirements and factors that might lead you to migrate your make-based build system include the following:

  • Your developers are comfortable with the UNIX command line environment.

  • Speed of implementation is important; a complex build system is usually easier to port than to rewrite.

  • The application migration team is using a UNIX portability environment, such as MKS Toolkit, Interix, or Cygwin, or it uses specific Windows versions of UNIX tools (such as gcc). In cases such as these, it is economically sensible to use the same approach for the build migration as for the application migration.

  • The current build system makes extensive use of the UNIX toolset and features, and it is robust.

  • The scope of your initial solution constrains you to a make-based migration for the first release, even if the eventual vision is for a completely new Windows tools-based build system.

In practice, often the single most important factor is the staff available to do the migration. Familiarity and knowledge are often the best guide to a fast implementation. If the developers are comfortable with make and UNIX systems, they will often find reasons to migrate the build system; if the developers are comfortable with Visual Studio and not with make, they will often find reasons to develop a new build system.

Note: If you decide to rewrite the build system instead of migrate it, the technical information in this document will help you in analyzing your current build system. However, there is no guidance on implementing the new build system.

Assessing Project Risks

Before proceeding to the development of concrete project plans, a final step in the Envisioning Phase is to recognize the risks that the build migration project entails. The team identifies risks, creates an initial risk assessment document using the methodology described in the UMPG, and prioritizes the risks. Then they focus on managing the highest priority risks.

The following list of risks that are specific to build migrations supplements the UMPG list of common risks for any migration project.

  • The new construction mechanism is unfamiliar and requires more effort than expected to stabilize.

  • The old build system is poorly understood and fragile, and the migration breaks it.

  • An incomplete assessment causes scope creep, increasing work above what is estimated.

  • The build system does not capture all necessary construction information, leading to additional design work.

  • If the application developers are doing the build system migration themselves, you may not have a clearly-defined pilot and you run the risk of the build system moving almost imperceptibly from the sample application into the production environment. The danger of this approach is that the system will accumulate unrecorded changes to scripts and the environment.

  • A lightweight process approach is chosen for conducting the build process migration project, but unworkable choices are made as result of inadequate analysis and review; as a result, more effort is expended to backtrack from development “dead ends.”

One of the tenets of the Microsoft Solutions Framework is that the team can significantly improve the odds for project success by reassessing and managing project risk continuously throughout the project. Each team member is responsible for keeping the other team members aware of new risks and of any change in the likelihood of known risks. As the project proceeds from one phase to another, it is likely that some risks can be retired but new ones will be identified. Each team member is also responsible to mitigate and prevent risks where possible. The Program Manager reviews the list frequently and drives modifications of the list.

Summary

By the end of this phase, the following should have been completed:

  • You have identified your core team members.

  • Your team has decided on the solution concept — that is, whether the build system will be created anew for Windows or be a migration of your existing makefiles onto Windows.

  • You have an inventory of your current build process.

  • Your team has drawn up an initial risk list.

  • You have approval from the project team, the customer, and the stakeholders of the major deliverables for the Envisioning Phase, including the vision/scope document, the solution concept, and the risk assessment.

Download

Get the Solution Guide for Migrating UNIX Build Environments

Update Notifications

Sign up to learn about updates and new releases

Feedback

Send us your comments or suggestions