Once the downloads are completed and ready, you can begin the installation process as follows:


  1. First Install the Git package where the Razor server will be running. Select all the default settings and complete the installation Note: DO NOT change the default installation folder

  2. Install the MariaDB on to the C drive but install the Database on the separate volume by following these instructions:
    1. Create the database directory on the separate volume i.e., G:\MariaDBRazorDatabases\Data

    2. Next proceed to install the MariaDB on the C Drive but on the following step:

    3. On the default instance properties window, enable access…, and Use UTF8 as the character set. Also, make sure that you remember the password entered

    4. Use the browse button to point to the new data directory

    5. Since this is where most of the growth is using a separate volume makes some sense.

    6. Click Next

    7. On the second default Instance Properties page make sure it looks exactly like below


    8. Click Next

    9. Click Install

  3. Next install the Razor Administration tool


    1. Click on Next

    2. Accept the License Agreement and click next




    3. Leave the Default settings DO NOT change the installation Folder

    4. Click Next


    5. Since the database is local, leave these settings as they are. If they are not change them to the Database server and port number as needed

    6. Click Next

    7. The Razor Administration tool is now ready to install - Click Next



    8. Click Close to complete the installation



  4. There should be an Icon on your desktop that looks like:



  5. Double Click on the Icon to begin the final phase of the installation


Razor 6 Administration Tool Installation Final Configuration


  1. When the Icon is clicked for the first time there are some final configuration items to complete.



  2. This first configuration is to install the user that communicates between the Admin tool, server and client. Without it, Razor Agile cannot function. You must have the database root password to install this user (See step b above). If you click on No, the program will exit

  3. Click Next



  4. Enter the root password for MariaDB from step v above.

  5. Click on Done

  6. Click on close and the next window will appear. Select yes



  7. The next screen is asking for a Razor Administration tool administrator. This account is only used for the Administration Tool. Click on Yes.



  8. The suggested user is presented, but you can change the user if desired. The login and passwords have restrictions such as login length and password strength. Once the login and passwords are set, click Done. You must provide this login and password to the Razor Administration Tool each time you use the tool.


Welcome to the Razor 6 Administration Tool


Using the Administration Tool


  1. Logging into the Administration Tool




  2. Licensing and Encryption
    1. Add Razor Licensing. Allows the Administrator to add licensing for other servers. This will be discussed when the server is released

    2. Update Razor Licensing. When the license is expired and you have received new keys, this is where the keys are updated

    3. Current License Status. Shows how many users are allowed, how many users are connected and expiration dates for the licenses.

    4. Configure Encryption. See next section

    5. Request Permanent License. Provides a template for requesting permanent keys.

    6. Note: You can contact Visible Systems Corporation Sales by calling 315-363-8000 or sending an email to razor_sales@visiblesystemscorp.com


      The license agreement may be found at: https://visiblesystemscorp.com/Products/Razor/license_agreement.htm

  3. Configure Encryption






  4. User Authentication
    1. Configure Authentication Method. Razor Agile will use the internal MariaDB user/password database by default

    2. LDAP, Secure LDAP and Single Sign On (Linux) or NIS to authenticate users.

    3. Import Razor Password Files. The Administration tool can import the existing Razor 5 Password file leaving current settings for users intact.

    4. Add or update a Local user. Used by the Razor administrator to manage the local users.

    5. Delete a Local User. The administrator can delete a local user here.

    6. Note: Managing users at the Active Directory, LDAP etc. levels are managed at their source.


      Note: When importing a Razor 5 password file, the file must have read permissions and be accessible by the Administration Tool


    1. Click on the Configure Authentication Method and this screen is displayed



    2. Select any of the Authentication methods

      1. Local Razor Database contains all users in MariaDB

      2. LDAP will use the Domain LDAP server

      3. Secure LDAP will use a secure connection to the LDAP server

      4. For NIS, Single Sign on enter the Server nam


    3. Next Select Set or Reconfigure Server IP Address

      1. The first form will display all of the Active IP address that are available for this server.

      2. Select the IP address that all Razor Agile communications are to happen over



      3. Click on OK

      4. Next set the name of the server that is to be presented to the users. This name does not have to be the host name of the server




  5. Optional Import of Existing Issue formats


    1. Create a directory that is accessible to the Admin Tool. We will suggest Razor Imports

    2. Next, create a directory under Razor Imports that has the same name as the Issur form you are importing. For example:

      • Issues
        • IssueFormForm1
          • The subdirectory is labeled Form1

    3. If you have multiple forms create directories for each with the defaults file at the root



    4. Note the W or X defaults file is renamed to defaults.

    5. Next copy the files that you wish to import into the proper sub directory

    6. Next start up the Admin tool and select Import Razor 5 Configuration for use in new Git Projects




    7. Log in if needed


    8. Navigate to the Razor Imports directory and click OK


    9. The form should appear listing all the forms possible to import from the defaults file




    10. Notice there are 3 forms in this defaults file. Make sure that the Attributes, Permissions, Insensitive, Roles and Command files match the from you wish to import


    11. Select the form and click on OK. The form will and all supporting information is placed into the database


  6. Razor Projects
    1. Create a New Git Based Project



      1. The Browse for Repository option provides a Directory browser so the Administrator can select the location where the new Project is to be created

      2. Project Directory will display where the new Project is to be created

      3. Git Universe Name - All characters are allowed except spaces

      4. Group Name - All characters are allowed except spaces

      5. Issue Type Select.

        1. Standard will have the new Project use the built-in form for Issues, Versions and Baselines

        2. Use Custom Format. If the Administrator has imported an existing Razor5 Defaults, Insensitive etc. Files, then when this option is selected the available formats will present themselves in the Available formats pull down.

      6. Versions Configuration: Files must change before checking in and Must Attach an Issue to a file check out

      7. Baseline Config. Can only update a Baseline based on an Issue

      8. Administrator’s Email. Used by Git

      9. Issue Prefix: Single letters are still allowed, but this can be any phrase between 1 and 8 characters. For instance, an Issue prefix can be: I, Issue, Docs etc.

    2. Add a new group to an Existing Project.

      1. Select the Project to add the new group to add to

      2. Enter a group name

      3. Issue type select. Same as above

      4. Select what to add. Complete adds (Issues, Versions and Baselines), Issues only or Versions and Baselines only

      5. Versions Configuration

      6. Razor Administrator’s Email

      7. Issue Prefix as before

  7. Fixing an Imported Issues Form
    1. Bring up the Razor Client and log into Issues

    2. An imported for may look something like this

    3. Note the text boxes are a bit shifted to the left and some items are located under others. Close the open issue but do not log out of the issues program.

    4. To fix this bring up the Admin tool and select Edit Custom Configurations

    5. A warning message will appear

    6. Please heed this message and see the section on backing up the databases

    7. The next screen will be which database to edit select attributes

    8. The database editor will now be presented.

    9. Scroll down until you see the field you need to change

    10. Next slide over so the xLocation, yLocation are visible

    11. Click on the X location field for the attribute and increase its value to move the item to the left or decrease its value to move it to the right. If you need to move the Y location decreasing the value move the attribute up and increasing moves the attribute down.

    12. Click on Update Database and select new issue on the Client tool. If the attribute is in the correct place you are done. Otherwise close the issue and repeat steps 11 and 12 until every look great.

  8. Database Maintenance
    1. Backup Database: Allows for complete backups of all Razor databases or the backup of individual databases

    2. Restore Database: Will restore an existing backup

  9. Adding Commands to the Command Pulldown
    1. Before you begin you will need two pieces of information

      • The Issue form name

      • The Issue form index

    2. Start the Admin Tool and select Edit Databases

    3. To get the form name select Attributes

    4. Write down the information Note case for the Form name and select close

    5. Next select Commands

    6. Click into the form name box and enter the form name

    7. Next select the whichTool column and enter 1 for Issues 2 For Versions or 3 for Baseline commands

    8. Next select CommandName column and enter the information to show in the command pull down

    9. Finally select CommandScript column and enter the actual script location

      • Note the direction of the slashes / not \

    10. If you need to add more lines select add row, otherwise click on update Database

Razor Server Installation


  1. Navigate to where the files were downloaded to and double click on the setup.exe file

  2. Click on Next

  3. Read the License agreement select I Agree if you are OK with the license, Click Next

  4. Select all the defaults. Note: DO NOT change the install directory. Click Next

  5. Click Next to begin the install process

  6. The server is now installed and started

Razor Client Installation


  1. Navigate to where the files were downloaded to and double click on the setup.exe file

  2. Click on Next

  3. Read the License agreement select I Agree if you are OK with the license, Click Next

  4. Select all the defaults. Note: DO NOT change the install directory. Click Next

  5. Click Next to Continue

  6. If you are not installing the client on the same server as the database as in the Test Drive configuration, then your Razor Administrator should have provided the information as to the Database server and Port number. Edit these fields as necessary and click Next.

  7. Installation is now complete and there should be an Icon on your desktop for the client

Razor Agile Desktop


  1. Double clicking on the Client Icon will bring up the Razor Agile Desktop



  2. The Razor Agile Desktop is the gateway to all of the tools that are available to the user along the left had side as well as the Applications pull down. The buttons along the bottom provide information on the release via the About button, details on the tools via the Details button and the Exit button exist the Desktop.


    One can use the TAB key to navigate through the selections or press the ALT+ the Letter for the desired functions. Pressing the enter key will select the highlighted function.


  3. Clicking on any of the tool’s buttons will bring up the Database Selection form.



  4. This tool allows for the choice of the Razor Server to contact in the event that your Razor administrator has set up more than one, the Project to connect to and presents all available local host IPs to use for commutations to the Razor Server. As before, use of the TAB key and the arrow keys make the selections quick and easy.


  5. Database is not avaiailable

  6. In the case that the Client detects thaty the database is down or may have moved, the following screen may be displayed. Please read it carefully and contact your Razor Administrator to see if the Database id offline or has moved



Sprints


  1. Razor Agile Sprints
  2. Razor Agile now has Superset to Issues that incorporates Agile Software development. This system uses Sprints and Stories to provide greater insight into the development process. It even incorporates rapid releases in the form when a story is completed, the Snapshot for that story is automatically updated with all the files worked on and associated to that story.


  3. Start Working with Razor Agile Sprints
  4. When selecting Sprints for the first time form the Razor Agile Desktop the following screen may be displayed




    The default is yes and if yes is selected the following screen will be displayed




  5. Creating your first Sprint


    1. Step one is to ensure that the correct Project and Group is displayed

    2. Next enter a Definitive Sprint Name. Note there is no checks on the Sprint name but it should be meaning full to the Project / Sprint

    3. Select a Sprint Start Date and End Date. Note the End Date has to be after the Start Date and is verified when the Create button is pressed

    4. The Snapshot Named field tiles this Sprint to and existing release or can create an entirely new release to the software. When clicked the following screen will appear



  6. Tying a Sprint to a Release
  7. This part of the Sprint System ties any completed story in a sprint to a release in Razor Agile which then if desired can be automatically deployed via Scripting to production.




    1. There are 3 choices that are available to the user

      1. Copy an existing snapshot. This system copies a snapshot that may be a full production release into a test release or a temporary release so the changes can be verified. It can then become the main line release if desired

      2. Use existing snapshot. This will update the current release snapshot of the product

      3. Create New Snapshot. This is used in the case where there a no snapshots to copy or use. Generally, this is a brand-new product.

      Once all is complete the Main Sprint Page will look like this




  8. Creating the first Story
  9. Double clicking on a new Sprint will bring up the following




    Click on Yes and this screen will appear




    Since Stories are Issues the Brief Description will be translated into the title of the Issue and the Detailed description will be translated into the Problem Statement


    Once submitted the Story Board will show up and look a bit like this:




    Double clicking on any story on the Story Board will bring up the associated Issue




    At this time, Razor Agile does not have a role per say called a Scrum Master. However, one can be set up in the Roles and Permissions Tables which will be discussed in the Appendix on how to implement.


  10. An Active Story Board Example


Issues


  1. Razor Agile Issues
  2. Razor Agile’s Issues functionality remains pretty much the same as Razor Classic’s Issues. The main Issue form is completely redesigned to make selecting items quicker but the old methods for selecting items remain


    Since Sprints are intergraded into Issues there is a selection to show Sprint based Issues only




  3. Let’s explore the Main Issue Display
  4. These are descriptions of the righthand controls. Some of these like the Change Group and Change Project have the same functionality as the Groups and Project Selection on the Menu bar.


    There are addional options with the View and Commands selections on the Menu Bar. However, the Command selections are only available if your Razor Administrator has set them up for you. These are usually scripts or other programs that provide additional functionality to the Issues System




    When an Issue is submitted the form will look like this:




    The State field shows that the Issue is Submitted with it’s Priority set to High. There are no attachments at this time and the full title is displayed.


  5. The Issue Form
  6. The Issue form that is included with Razor Agile is very basic but it is a good starting point for new users.




  7. State Driven Form Guide
  8. The Issues form features what Visible Systems calls a state driven guide to filling out the form. If you notice in the form above, several fields are grayed out, but already filled out and some are open and have a yellow background color.


    There is a table in the database that drives the field guide that is called the Insensitive table. This table along with the roles and permissions tables can hove profound affects on how a user is guided in filling out the form. This can be used to ensure a consistent and repeatable process for describing a problem to the actual fix that was applied to the problem.


    What this means as the states (Submitted 🡪 Approved, or Submitted 🡪 to Rejected) and so forth are changed, different areas of the form are opened up or closed off as needed by your process.


    The setting up of these tables will be discussed in the appendix of this manual.


    Here is an example of a submitted Issue set to the Approved State




    Notice that new fields have been opened up and highlighted in Yellow. Also, the Activity and Attach buttons are now available and will be discussed below.


    Once the form is filled out the submit button is selected and the database is then updated with the new information and the main display is refreshed.


  9. Activity Button
  10. When an Issue is set up to be required to interconnected with Versions and or Baselines the Activity button will provide insight as to what the issue was used for.




    In this case this issue was used to Introduce files into the Versions system. It provides additional information as to Who and when the files were introduced and which files were introduced.


  11. Adding Attachments
  12. Sometimes a problem that an Issue must address is too complicated to be expressed in the Description of problem section or some other supporting documentation is required for final approval that all fixes have been properly applied before releasing the code to the public is approved. This is where attachments come in very handy.


    1. The Issue must be in the Approved State to add an Attachment

    2. Bring up the Issue and select the Modify Button at the top of the Issue and then select the Attach button

    3. The following screen is displayed



    4. Click on the add button and navigate to the file to add. It can be any file type for instance Word Doc, Excel spread sheet



    5. The state will remain pending until the OK button is selected. This is to allow for multiple files to be added.

    6. Once the OK button is pressed, the file is added



    7. Once the file is added clicking on the file will open up the options that will allow viewing the file, if viewable, removing the file, exporting the file or show the history of the attachment.

    8. Note: Removing a file will not remove it from the display. It will be highlighted as removed but it’s history will remain but can no longer be downloaded or viewed.





Versions


  1. Razor Agile Versions
  2. The versions program is the backbone of the configuration management aspect of the Razor tool suite. Versions provides a straightforward mechanism for controlling, monitoring, and archiving changes made to files in your development environment.



  3. The Main Display of Versions
  4. These are descriptions of the righthand controls. Some of these like the Change Group have the same functionality as the Groups Selection on the Menu bar.



    There are additional options with the View and Commands selections on the Menu Bar. However, the Command selections are only available if your Razor Administrator has set them up for you. These are usually scripts or other programs that provide additional functionality to the Versions System





  5. File Introduction
    1. There are 2 methods for file introduction: Razor Classic and Drag and Drop

    2. Both have similar Interfaces which have been designed to be easier to use

      1. For Classic File Introduction select the Introduce button from the Versions Window



      2. On the right side of the Introduce window, in the box labeled available issues list you will have a list of the current Issues. By left clicking on an Issue the Issue title will appear



      3. By right clicking on the selected Issue, it is transferred to the Issues list to be used for this file introduction. One can use the standard Windows feature of Alt clicking or CTL clicking to select one or many issues to be included



      4. You can now proceed to complete the file introduction as needed

    3. Drag and Drop File introduction

      1. Is basically the same as the standard file introduction

      2. Simply drag the file or folder that you wish to introduce onto the main Versions Window



      3. Click on the OK button and the Issues selection Window will pop up



      4. Select the issues as needed and right click to include them and Click Okay

  6. The Versions Screen After Introducing Files


  7. As one can observe, the directory is now showing up on the Versions Screen. By Clicking on the plus sign, the directory is opened and all the files are present.





    Razor attempts to learn the file Icon that is associated with the file type. In most cases it represents the file type quite accurately. One will also note that each of the introduced files are assigned a revision code 1.1. Even though the file is “introduced” into the Git repository, Razor Agile tracks the file revision / hash code for each file for a more human readable format. The importance of this will become more apparent as you read on.



  8. Basic File Operations after Introduction
  9. By double clicking on any text-based file a read-only display is presented of that file’s contents. Note if the file is a binary file a warning message is displayed, but not the file contents.





    Also, by selecting a file and then selecting Utilities 🡺 Info the following is displayed




    The file history will show in detail every action that has taken place on that file. When and who checked the file out for edit or read-only etc.


    The Utilities 🡺 File Diff will be discussed below.


  10. File Check Out Read Only
  11. There are times where a developer may need to get a copy of a file for use in another project or just want to get a print out a better view of the file.



    Simply select the file and then select the Check Out Rad Only button





    And the following screen is displayed





    The file name and directory are displayed as shown. The browse button is used to select where the file is to be written. In this case M:\



    If the Path is absolute is checked the directory structure for the file is removed. The file location is in this case M:\ActivityTest.sh



    The Available Versions pull down is unique. If left as show above, the latest version of the file is received from the Git repository, However, if there are many revisions on the file i.e., 1.1, 1.2, 1.3 then selecting one of those revisions will get that file version from the Git repository.



  12. Check Out File for Edit
  13. Now the work begins. An Issue or Story from a Sprit has been assigned to you. Time to get the files needed to begin work. The process is started by selecting the file or files needed and clicking on Check Out for Edit Button





    1. Left clicking on any Issue in the Available Issues List will display the Title for that Issue

    2. Left clicking on any Issue in the Available Issues List will display the Title for that Issue

    3. The Display Issue area allows for the filtering down of the Issues list. The default is to show all Issues. Selecting the Assigned to Me button will show all the Issues that are assigned to this person. Sprint Issues Only will provide a pop up that will allow the selection of the Sprint, then display Issues (Stories) assigned to that Sprint

    4. Path is absolute check box when selected will remove the entire directory structure from the files and deposit them directly to the checked out to destination

    5. The title field is mandatory and should be a brief description of what is being done

    6. Description field is optional. More details can be placed here

    Once the form is filled out as shown below click on the OK button and the file will be checked out and assigned to the person doing the check out





    Once the file is checked out the person who has the file checked out is displayed on the main versions screen





    Now if you remember the Activity file, it now looks like this:





    It shows that the file is checked out, by who and when.



    Also remember the Info file, it now looks like this:





  14. File Check In
  15. After files have been modified, they must be re-entered into the database. To do so, the user first selects the relevant files from the main display of the versions program and selects the Check In button.





    Under File Control one can select what is to be done with the file. The default is to Leave a read-only copy in the location of where the file was Checked out to and is the recommended action. Take the files will bring the files back into the Git repository, then delete the files from the location where they were checked out to. Check the files back out for edit is not currently implemented at this writing.



    Now if the Razor Administrator has required that the file must change for a check in and the file was not edited, the following screen will appear





    And nothing has been done, the file remains checked out



    If the file was changed and checked back in the Versions main display will look like this





    Note that the file revision has now been incremented to 1.2. The changes to this file are reflected in the Activities and Info displays respectively.



  16. File Diffs using GUIFFY

  17. Razor does not come prepackaged with the Guiffy Diff tool bit it pre licensed for the tool. This is a major change from Razor Classic which allows the user to upgrade the Guiffy tools as needed and not have to wait on a new release from Visible Systems.



    Here is the process to execute a diff on the file we just updated. First Select the file, then Utilities 🡺 File Diff





    The Main Diff form will show up. Here is an example with some info





    Once the selections are made for what is to be shown and which versions to compare click on Apply



    This screen will appear if you have not yet installed the Guiffy tool on this computer





    If you select No, a very basic diff tool is used to display the file differences





    If you select yes, you will be taken to the Guiffy Web site and please download the 64-bit version of the tool. You DO NOT have to request a set of temporary keys as Razor Agile is pre licensed for a full version of the tool. Install the downloaded file and please do not change any of the default settings. Now click on apply and a new display will appear





    All options on the tool are available to the user as needed.



  18. File Branching

  19. Branches are deviations from the main development line for a file. They are a convenient mechanism for allowing two or more people to be working on the same file at the same time (perhaps for different goals).



    A common scenario is having one person working to add new features to the product, while a second is doing bug fixes on prior versions



    The version numbers of branches can be a little confusing, and warrant a quick discussion. Version numbers on the main development line have only two parts; a major and minor number.





    Branches have 3 parts to their numbering scheme. The first two parts represent the point at which the branch split off the main line. The third number indicated the branches revision level.



    Looking at the main Versions page, we discover that Mike C has the file we were tasked to work on already checked out. We need to Brach this file. We begin by highlighting the file then select the Branch Button





    The Branch form is pretty strait forward. It requires the selection of the file version to branch, a reason for the branch and a description. Then assign an Issue for traceability and then select OK.



    The main Versions Page now looks like this





    The Branch can now be checked out edited checked in checked out again to continue editing just like any other file on the main line. Likewise, the file that Mike C has checked out can be checked in and checked out again so there are 2 independent development paths for one file.



    It is expected that branches are used as a temporary means of allowing concurrent development on a single file. Sooner or later, the edits made to the branched line will be incorporated into the main evolutionary line for the file.



    To begin the process of Terminating a Branch, the main line file and the Branched file must both be checked back into the Razor Database.



    To signal the end of the utility of a branch, highlight the branched file in the main scrolling list and select the Terminate Branch button and the following will appear





    The default is Yes to merge back into the main trunk. If No is selected, then the Branch is terminated and the code changes are lost.



    Selecting Yes will bring up the following for Traceability for the Merge





    Select an Issue to this Merge and Select Okay





    There are 2 options for the merge. Method 1 brings up the Guiffy GUI, if installed, to help visualize the code that will be merged into the main trunk. The user has the ability to accept or delete lines that may or may not be needed etc. prior to the merge completion.



    Method 2 is allowing the Guiffy tool to automatically resolve the merge of the 2 files and create an amalgam of the two. In either case once the merge is complete the main trunk is automatically checked out the newly merged file is then checked in and the revision of the main truck is bumped up one





Razor Agile Baselines


  1. Razor Agile Baselines

  2. The Baselines program is the final piece Razor Agile. It provides a mechanism for defining which unique combination of files and versions "belong together" for the sake of a release or product build. This section discusses how to use the Baselines program from a user's perspective.



    Within Razor Agile, a "group" is an organizational model. The Versions program allows you to define which files belong within which groups. All files in the same group are assigned a similar set of attributes, although the attribute collection may vary from group to group.



    Although the Versions program provides a nice vehicle for monitoring changes on a file by file basis, it's often necessary to monitor changes to your effort from a broader perspective. Your product at any point in time is defined as the union of a unique combination of files, at a unique mix of their relative versions.



    A Baseline or Snapshot can be thought of as a collection of specific files that have been grouped together for a special reason. One reason to group files together into a Snapshot is for release/build management. As new releases of a product are developed, the files (implying specific versions of those files) are gathered together, tested as a whole, and ultimately released as a whole.



    The exact state of each file, as they relate to the Snapshot, can be reconstructed. A Snapshot is what forms the relationship among specific versions of files. Files are no longer thought of as individual, autonomous entities, but rather as what the combination becomes. An individual source file that performs mathematical calculations by itself is not worth much until it is packaged within the context of a system.



  3. The Theory behind Baselines

  4. If we imagine a simple group containing only four files, then we could diagram how each file has evolved from version to version, as well as how Snapshots come into play.





    Each row of the above diagram shows how a single file within the group evolves from version to version. The vertical (blue) lines which flow behind the rows represent threads. Each thread indicates a relationship of which file/version combinations belong together. For example, the left most Snapshot on the diagram brings together main.c:1.6, init.h:1.6, color.c:1.2, and static.h:1.9. The only difference between the second and third Snapshots on the diagram is that they reference different versions of the file color.c.



    The meaning and utility of a Snapshot is completely up to the user. Each Snapshot may be given a unique name, and may evolve over time. The diagram above may be represented as four different named Snapshots, or a single Snapshot that has gone through several changes itself. Often, each Razor group will have a Snapshot which defines the file/version combinations constituting a product shipment or release. This special Snapshot evolves over time to reflect the contents of each release. Separately, Snapshots may be defined to remember which combinations were compiled for the sake of lab testing, or to create a test mix of files for quick experiments. The scope and utility are completely up to the user.



  5. The Main Display of Baselines

  6. These are descriptions of the righthand controls. Some of these like the Change Group have the same functionality as the Groups Selection on the Menu bar.



    There are additional options with the View and Commands selections on the Menu Bar. However, the Command selections are only available if your Razor Administrator has set them up for you. These are usually scripts or other programs that provide additional functionality to the Baselines System





  7. Creating your first Snapshot in Baselines

  8. Once files for the project are intorduced in Razor’s Versions, and some editing has occurred along with some basic testing it is time to create the forst Snapshot of the current state of the code.



    There can be up to 3 options, based on what your Razor Administrator allows. We will go through each now.



    1. It begins by clicking on the New Snapshot button on the main Baselines form.



    2. Click on each file. A new pop up will appear allowing the choice of the version of the file to include in this Snapshot.





      By selecting the version and then Update the file will be included in the Snapshot



      Once you have all the files selected then Click on the Create New Snapshot button



      It’s straightforward from here, Create a Snapshot name – no spaces please, then the purpose of the Snapshot and so on. Then click the OK button.



      The main screen will now show your Snapshot



      If you double click on the Snapshot the display will show the files that are included and those files which are not



      This can become tedious if there are a lot of files to include so let explore the other options.



    3. Manual Selections

    4. The second method begins by selecting New Snapshot then selecting Manual Selections.

      At this time one can select the desired files for this Snapshot by clicking the check box neext to each file.



      Or click on the Check Box to Select All files.



      Once the selections are complete, then click on the OK button and fill out the new Snapshot form as previously shown.

    5. By Issues

    6. The final method begins by selecting New Snapshot then selecting By Issues



      This form has several areas that are interconnected. File State Selections are disabled until Issues are selected. The user must select at least one Issue but has the option to select several. The Issues are selected by right clicking an Issue. It is then moved into the Selected Issues field which then unlocks the File State Selections Group.



      The user then selects which files are to be included in this new Snapshot by selecting the various states of the files.



      Once the selections are complete, then click on the OK button and fill out the new Snapshot form as previously shown.

  9. Update an Existing Snapshot

  10. As development progresses, and new releases are ready for prime time, the attending Snapshot should be updated.

    By double clicking on the Snapshot to be updated the user is presented a screen that will highlight all of the files that have has their revisions updated, that is been modified by the development staff.



    By selecting the By Issues button the following screen is displayed



    By selecting the Issues that were used for all updates, and then by selecting the desired file States a complete list of file to be included or updated in this selected Snapshot are presented. Next click on the OK button.



    Notice that the Snapshot Name is Greyed out – can’t be changed. But the Purpose field is open and must be filled out. Also, the State area is opened so that the state of this Snapshot can be changed if needed.

    Once everything is updated click on the OK button, then the cancel button.

    The Snapashot is then Updated



  11. Extracting a Snapshot

  12. From the main Baseline Panel, selecting the Extract Snapshot button the following panel shows up



    The top left corner of the panel contains a list of all the Snapshots for the indicated Razor group. As different Snapshots are highlighted on that list, the scrolling list in the top right of the panel will update to show various versions of the Snapshot. The purpose and Description fields will also be updated as necessary to show what was entered at the time of creation.

    The Set output directory button allows the user to navigate to the directory where the files should be placed.



    Once all of the selections are made, click on the extract button to get the files into the selected location.

  13. Pushing a Snapshot

  14. NOTE: This is a preliminary set up procedure and is nowhere a complete procedure. This procedure will be updated as needed. Currently the button for this process is disabled

    Setting up Razor Agile to have the ability to push a Snapshot to a production server requires some understanding of Git, the production Server and SSH. There are several steps necessary to get this accomplished so we will begin.

    NOTE: For the purpose of these instructions, we are assuming a Windows Source and destination.

    1. Downloading PuTTY to Get Started

    2. Step one is to get the PuTTY toolset from the following URL and install it on both the Razor Server and the Production Server.

      https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html

      It is suggested to download the 64 bit MSI installer package. Once downloaded install the package on the Razor Server and the production system.

    3. Downloading PuTTY to Get Started

    4. This section will be updated as needed to ensure that the proper Razor User for the Client/Server interaction is correct. We are determined to not have to create a key for every user but to provide a means within the Razor Client/Server to make this a seamless operation.

      1. Launch the C:\PuttyTools\puttygen.exe tool.

      2. Select the 'Generate' button.

      3. Move the mouse about the GUI's blank area to add a unique, random element to the key generation process.

      4. The key generation can take several minutes to complete.

      5. When key generation is complete, the GUI will display the public key, key fingerprint, key comment, as well as fields for specifying and confirming the key 'passphrase'.

      6. Specify a 'passphrase' that will be used to safeguard your key. The passphrase should be handled like an account password.

      7. Select the 'Save public key' button to create a local copy of the key, e.g. C:\PuttyTools\puttyXpPublicKey.

      8. Select the 'Save private key' button to create a local copy of the key, e.g. C:\PuttyTools\puttyXpPrivateKey.ppk

    5. Setting Up the Server Repository

    6. The first step is to navigate to the Baselines Repository for the group that this service is to be implemented on. It is located on the Drive/Project/BASELINES.Group that was setup by your Razor Administrator.



      Next navigate to the .git repository that this service is to be installed on and open the config file in your favorite editor and add the following lines:

                              [core]
                                  repositoryformatversion = 0
                                  filemode = true
                                  bare = false
                                  logallrefupdates = true
                              
                              [remote "live"]
                                  url = ssh://<FQDN of Destination>/Upper directory /<.Destination Git Repository>/<Final Location>/
                                  fetch = +refs/heads/*:refs/remotes/live/*
                              

      Some notes here:

      • FQDN of Destination: This is the production server where the code is to be released to. Not the Razor Server.
      • Upper Directory: This is the location of where the Git repository is to exist. Should be hidden (dotted) directory.
      • Destination Git Repository: This is the directory where the program will eventually reside.

      So a URL may look like this:

                                  url=ssh://ProductionServer.someplace.com/.HiddenRepository/ReleaseFolder
                              
    7. Setting up the Production Server

    8. The first step to setting up the production server is to install or ensure that Git is installed.

      Next, if not already done, is to create the production upper-level directory where the code executes from, or in the case of a product that is available to the public to download, the download area.

      Then a hidden Git repository is created somewhere on the production server that is not within the release area using the command:

      git init --bare

      Afterwards, create the following script in .git/hooks/post-receive:

                  #!/bin/sh
                  git --work-tree=/var/www/html/apps/labor --git-dir=/var/.gitRepository/labor checkout -f
                      
    9. Copying a Snapshot

    10. A developer may at some point want to branch off the main development path and tyr something new without disturbing the current release of the code. To do this the developer selects Copy Snapshot from the main panel.



      On this panel the developer selects the Snapshot to Copy and the Version of the Snapshot. Next, the developer must enter a New Snapshot Name, then select the State and the Reason for Copy, finally, click on the OK button.

      And the main panel is updated with the new Snapshot.



    11. Comparing Snapshots

    12. It is often important and useful to be able to see what differentiates one thread from another. Fortunately, there is a simple means of doing just that. By selecting the Compare Snapshots from the main display, the following panel will appear.



      Using the mouse, the user finds which Snapshot and version is to be on the left, and which is to be on the right. Selecting the Compare button at the bottom of the panel runs the analysis.

      The output lists all files currently in the group along with each file version. The last column identifies the type of change as "No change," "Included," “Version Changed” or "Excluded."



      The user has the option to Copy to Clipboard so the output can be applied to a report or into a file as needed.

Scripting


Scripting within Razor Agile environment is very flexible. When a project is created a directory labeled RazorScripts inside this directory are directories for each tool. These subdirectories then contain some basic bash shell scripts that have before and after extensions. The before and after scripts are the actions that can be programed before or after a particular Razor Agile operation.

  1. Using .before and .after Scripts

  2. The before scripts are actions that Razor Agile will take prior to the operation that is in what is called the descriptor, such as checkin.before, and the .after scripts are actions that are taken after, such as checkin.after. Maybe a practical example is in order here.

    For instance, let’s say prior to checking out a file within Versions you need to verify that the developer has attached an Issue or Story to the file that is being checked out for traceability. The file checkin.before is where this can be programmed. But how?

    There are two methods to do this: the first is to put everything in the .before script or use it to call another script. An example of the latter:

                    #!/bin/sh
                    # The 'shebang' above will reflect the script type to be used
                    # sources such as sh, ksh bash, php, python, etc are available
                    # The use of bat files, visual basic scripts, or powershell, etc 
                    # can also be run.
                    # This Script calls the script(s) that are run before.
                    # Return codes from the called script must be a
                    # zero for a clean exit or an eleven if an error occurred.
                    # The eleven is used to display error messages back to the 
                    # user.
                    # #########################################################
                    /Razor/RazorAgileUniverses/RazorScripts/Versions/verifyFileCheckOut.bash "${PASSED_PARAMETERS}" "${VERSIONS_FILE}"
                    ret=$?
                    exit $ret
                    

    Now as you can see in the above example, the .before script points to the file that actually does all the work. We will get to the return variables soon and see the next section for the environmental variables.

    Now the script verifyFileCheckOut.bash looks like this:

                #!/usr/bin/bash
                #
                # By placing a dash x (-x) after the /usr/bin/bash, the script will output all
                # debug information
                # Note: All Client Environmental Variables are passed from the client to the server.
                #       The Server then determines the remaining from the database and passes that
                #          Data to the scripts. Full list to follow
                #
                # First, this is how the utils script is sourced
                #
                . "${RAZOR_HOME}"/scripts/rz_utils
    
                ERR_CODE=11
                ERR_FILE="${RAZOR_TMP}"/Razor_notice.${RAZOR_PID}.${ERR_CODE}
    
                #
                ###########################################################################
                #
                #
                # Standard Setups complete
                # Now check to see if an issue is related to this introduction
                # but don't error out if this is a document
                #
                issuesDirectory="${RAZOR_PROJECT_DIR}"/ISSUES."${RAZOR_GROUP}"/"${1}"
    
                if ! [[ -f "${issuesDirectory}" ]]
                then
                    if [[ "${RAZOR_GROUP}" != "documentation" ]]
                    then
                        echo "Sorry that the file: $2" > $ERR_FILE
                        echo "cannot be Checked Out of the Razor database at this time." >> $ERR_FILE
                        echo "" >> $ERR_FILE
                        echo "It seems that there is no Issue or Sprint assigned to this file Check out." >> $ERR_FILE
                                
                        echo "" >> $ERR_FILE
                        echo "Thank You" >> $ERR_FILE
                        echo "" >> $ERR_FILE
                        echo "Razor Configuration Management Tool" >> $ERR_FILE
                        exit $ERR_CODE
                    fi
                fi
                # exit 11
                exit 0
            

    A couple of things to note here. The first being the line:

    ERR_CODE=11

    The Razor server recognizes two exit fields. An exit 0 means that all is well and we can move on. But if the script returns with an error 11, then there was an error in the script. The file that the server knows about is as follows:

    ERR_FILE="${RAZOR_TMP}"/Razor_notice.${RAZOR_PID}.${ERR_CODE}

    The server, when it receives the error 11 response from the script, will read this file, format it, and send the contents to the client to be displayed to the developer.

  3. Do I have to use bash shell scripts

  4. Short Answer is no. The before or after scripts can be any programming language you are familiar with. The only caveat to what programming language you use is that the extension is .before or .after. So feel free to use C, C++, C#, php and so forth. However it is up to you to make sure that the programs that you use can access the set environmental variables.



  5. Razor Agile Server Environmental Variables

  6. These Environmental Variables are created by the server when a script request is detected by the server. They should not be changed at any time by any scripts unless noted below.



  7. Razor Agile API

  8. The API for Razor Agile contains 2 types of commands. Those that do not involve the entire server engine and those that do. The commands that require the server engine must include the keyword “console” as shown in the following items.

    Standard Commands

    To execute these standard commands in the console, first start a Windows Console and then enter:

    cd c:\Program Files\Visible Systems\Razor Agile Server

    Once there, enter the commands as listed below:



    Server Interactive Commands (more to follow)



  9. Standard Command Usage

  10. Executing Standard Commands

    To execute these standard commands in the console, follow these steps:

    1. Start a Windows Console.
    2. Enter the following command to navigate to the Razor Agile Server directory:
    3. cd c:\Program Files\Visible Systems\Razor Agile Server
    4. Enter the desired command as follows:
    5. Razor6Server.exe id
    6. The command will display the output on the console.

    To run the command via a script, refer to the next section on Interactive Commands.



  11. Scripted Command Usage

  12. Running Server requests from a Script no matter what type the user must inform the server that it is to run the command in “console” mode. This is because the Razor Agile Server is running as a service and services cannot normally be accessed from a command line. However, by using the past parameter when calling a RazorService command the server will execute the command and return the results to the Script.



    Something to note here is that the error paths return a robust parcel of information back to the script. It may make it more difficult to test for this information, however it will indeed speed up development of a script as the programmer will know what is amiss in their script.



    One last thing to note. The system_setup script supplied by Visible Systems Corporation and installed when the server is installed is for the most part complete and tested. But, if while developing scripts and you are required to update any of these, please send the updates to razor_support@visiblesystems,com so we can include them in our next release. The install program will overwrite these locations.



    Visible Systems is providing sample scripts for your use and or modification. Each script will demonstrate the proper calls and return values. These scripts are contained in a ZIP file which can be downloaded from this location: http://fileLocationhere



    Once downloaded, unzip the files in a desired location. Next if on Windows use the File Explorer to navigate to where you unzipped the files, then Right click and select Git Bash Here option. This will bring up a Git Bash Shell it will look something like this:





    Note the directory format: /e/SampleAPIStuff. If you are going to specify file locations within a script this is the format to use. E:\SampleAPIStuff will not work at all.



    Next you will need to set the RAZOR_HOME path. So, enter EXPORT=” C:\Program Files\Visible Systems” and press the enter key. At this point, open any of the scripts in Wordpad or the editor of your choice, yes vi works here too and read the script’s passed parameters requirements.



  13. Running scripts from the Command Pull Down

  14. Each of the tools in Razor Agile with the exception of Sprints has available to the user the Command pull down in the main tool bar. If your Administrator has made commands available to the user this is where they will be available from. Sprints do not have a Command Pull Down available as they are a super set of Issues and can be worked with within the Issues Tool.



    Exit codes for Command scripts



    There are three exit codes for these types of scripts:

    On the return code 1 to return a message to the user it would look something like this:



    #/usr/bin/bash

    echo “This is a test

    And we are adding a second line to that test”

    exit 1

    Appendix


    Preload File Usage Example:

    Note: The Attribute (Originator) and the Result (RAZOR_USER) are separated by a single tab.

                echo "Originator<TAB>$RAZOR_USER" >> $RAZOR_PRELOAD
                    

    Passed Parameters Usage Example:

    This is for 2 passed parameters in a comma-separated list.

                if [[ -z "${1}" ]]; then
                    # Do something based on nothing
                    echo "Nothing passed in"
                else
                    # This will assume that only 2 parameters are passed.
                    # It provides a simple method for getting the goodies
                    passedVar1=`echo "${1}" | "${cutexec}" -d ',' -f 1`
                    passedVar2=`echo "${1}" | "${cutexec}" -d ',' -f 2`
                fi
                    

    Format for passed result is as follows:
    $updateThisAttribute,$item1,$item2,$item3
    Where $updateThisAttribute is the item that is to be updated within Razor followed by a comma and the item's values to be used for the update separated by commas.

                echo $result
                    

    Passed File from server to scripts usage Example:

    This file will contain a formatted Issue, full file from versions, or Baseline output. It can be parsed within the external script as any normal file would be.

                # $1 is the file path to the passed file, in this case, the Issue
                # The fourth item in the file is the issue name which we need to
                # Get so this is one way to do it
                ISSUE=`"${sedexec}"  -n '4p' $1`