Workspaces

Introduction

A user’s Fuze workspace defines the world in which he/she works and develops. Everything that a user needs to work with Fuze, create builds and releases, and to recreates builds and releases is defined by its workspace . The workspace itself is defined by the location and contents of the workspace.ini file.

Fuze Workspace

A Fuze workspace is a directory in your local filesystem that contains all of the source files necessary to perform a Fuze operation (for example, build, release, etc), as well as a text file workspace.ini. If it needs to be included in your Fuze operation, it needs to be found within your Fuze workspace.

_images/fuze-workspace.png

Warning

Fuze provides a large degree of development freedom. Therefore, you have the ability to do things in your build map or with your build commands that can, in practice, violate the concept of the workspace . We discourage this.

Advantages

Defining the Fuze world in this fashion provides several advantages:

  1. Provides an environment in which build map commands and directives will be compatible across platforms and across users.

  2. Provides either a sequestered, or a multi-product environment, based on the user’s desire and method of work.

  3. Provides an environment description that can be stored under configuration management along with the FuzeID that was generated when Fuze operations occurred within the workspace .

The Fuze workspace provides the mechanism for recreating a build or set of operations that led to any given FuzeID. Given any FuzeID, a workspace can be recreated on a local system that will generate the exact same products as were initially created with that Fuze ID.

Examples of Workspaces

The example shown below is of a “multi-product” environment, defined within a single workspace . This might be used by a developer who works in several repos and builds and debugs several products on a daily basis. The workspace encompasses all of the repositories and build maps required for the various builds and operations.

/code
    /repo1
    /repo2
    /repo3
    workspace.ini
    prod1-build-map.json
    prod2-build-map2.json
    prod3-build-map3.json

This next example could be thought of as a “sequestered” environment. For example, consider the developer who has been tasked with fixing a bug from a release that occurred 6 months ago and is currently in the field. A reasonable workflow for that developer may be to recreate the necessary release’s workspace in a separate area in his/her local file system so as not to disturb any other work that he/she may have ongoing. This workspace is contains 100% of the data and information that is necessary to debug and build the particular product of interest.

/tmp
    /repo1
    workspace.ini
    build-map.json

Creating the Workspace

A workspace may be created automatically by using tools provided by Fuze, or it may be created semi-automatically, or manually. No matter the method, a workspace requires 2 items:

  1. workspace.ini file (See details of this file below)

  2. At least one source code repository specified

The following sections describe how to create the workspace .

Creating the Workspace Automatically

Use the WebUI to create a downloadable version of a workspace.ini file.

You can find this utility under the “Work Locally” menu item:

_images/fuze-fuzeapp.png

Creating the Workspace Semi-Automatically

The semi-automated workspace creation requires that you have a pre-existing workspace.ini file. Once you have created your first workspace.ini file, you can freely copy it to different locations in your file system and create new workspaces based on its location and contents. When creating the workspace in this fashion (ie, manual creation and location of the workspace.ini file), the automated part accomplishes the pulling of all specified repositories.

To create the workspace in this fashion, use the following command in the same location as your workspace.ini file:

fuze --create-workspace [repo0:branch repo1:branch ...]

The repositories can be specified either on the command line as shown optionally, or within the workspace.ini file. If repos are specified in both places, the command line will take precidence.

At the conclusion of the execution, you will have created a workspace that includes a valid workspace.ini file along with any and all repositories specified.

Creating the Workspace Manually

To create a workspace , you may simply create (or copy) a workspace.ini file and then git clone one or more source code repositories into the same location as the workspace.ini file.

workspace.ini File

The workspace.ini file is a text file that serves 2 purposes:

  1. Defines the root of the workspace in the filesystem

  2. Supplies various pieces of information such as credentials and default formats to be used within the workspace

Required Contents of the workspace.ini File
[general] Section

The general section defines the user’s name and email address.

[general]
fullname="<First> <Last>"
email="<[email protected]>"

Example:

[general]
fullname="John Macdonald"
email="<[email protected]>"
[git] Section

The git section defines the user’s credentials for the BitBucket repository(s) to be utilized in the workspace . Fuze can utilize either SSH or HTTPS protocols. The git section contents required depends upon which protocol is to be utilized.

Warning

Note: if HTTPS is used, the password field is stored in plain text in the file. For this reason, SSH with keys is the recommended method.

For utilizing SSH protocol with keys:

[git]
protocol="SSH"
keyfile="<path_to_keyfile>/<keyfile>"

Example for Linux/MacOS:

[git]
protocol="SSH"
keyfile="/Users/johnmacdonald/.ssh/id_rsa"

Example for Windows:

[git]
protocol="SSH"
keyfile="id_rsa"

For utilizing HTTPS protocol with username and password:

[git]
protocol="HTTPS"
username="<bitbucket_username>"
password="<bitbucket_password>"

Example:

[git]
protocol="HTTPS"
username="jnmacdonald-idex"
password="<password>"
Optional Contents of the workspace.ini File
[repos] Section

The repos section defines the source code repositories that were/will be pulled to create the workspace . This section is ONLY utilized if fuze –create-workspace is called:

[repos]
repo[0]="<repo_name>:<branch_name>"
repo[1]="<repo_name>:<branch_name>"
...
repo[n]="<repo_name>:<branch_name>"

Note that the repo key name(s) can be anything, but MUST be unique within the file. This section is ignored if repositories are specified as arguments to –create-workspace

Single Repo Example:

[repos]
repo0="firmware:develop"

Multiple Repo Example:

[repos]
repo0="firmware:develop"
repo1="g3fwtesttools:development"
[output] Section

The output section defines the default search output format for the workspace:

[output]
format="json | csv"

Note that if –format <type> is specified on the search command line, it will override this default setting.

Example:

[output]
format="csv"
[build] Section

The build section defines the temporary location in your file system to use for the FTL:

[build]
workspace="<path_in_local_file_system_for_ftl>"

Note that if this section is not specified, Fuze will choose its own temporary FTL inside your file system. Each build operation will tell you where the FTL is.

Example:

[build]
workspace="C:\tmp"
[<product>] Release Automations Section

The <product> section defines the various configuration items required for release automation. Whenever a release function is initiated, Fuze looks in the workspace.ini file for a <product> section associated with the specified FuzeID. If found, it will use the configuration items found in that section to direct the automation process.

The detailed specification of the “release automation configuration” parameters can be found in the Release and Deployment page.

[<product>]
<release_automation_config[0]>=
...
<release_automation_config[n]>=

.. note::

    Note that each product requires its own specification.  There are no shared or common configuration items.

Example:

[firmware-v3]
sit_atf_plan_key=MON-MFWV3RT
qa_atf_plan_key=MON-MFWV3RT
release_atf_plan_key=MON-MFWV3RT
jira_project_key=FWG3
jira_release_project_key=RELEASE
jira_release_header=FWG3-V
release_ticket_type=Build
release_notes_markdown_file=fwg3_release_notes_v3.md
release_home_page_id=183877048
confluence_space=G3SW