Git Instructions for DevNet Users

These are instructions for DevNet customers to use the Git command line interface for version control system with One Network's SDK.

Instructions to Install Git on Windows PC and Authenticate with Github.com

Install the Git Bash command line. 

  1. Follow the instructions found here: https://help.github.com/en/github/getting-started-with-github/set-up-git
  2. Navigate to: https://git-scm.com/downloads
  3. Click the Windows button.
  4. Run the downloaded executable ("Git-2.25.0-64-bit.exe")

Create a Github user account. 

  1. Go to https://github.com/
  2. Click "Sign up"
  3. Follow the prompts to complete setting up your user account in Github.
  4. Note: We used Github in this example. However, it is not the only Git repository service available. Other popular products include Bitbucket and Gitlab.

Set up a SSH Key for Authenticating with Github

  1. Generate a new SSH Key on your PC
    1. Open Git Bash (or the regular command prompt)
    2. Run the command: ssh-keygen -t rsa -b 4096 -C "mnutsch@onenetwork.com"
      1. Replace the email address with your Github associated email address.
    3. Press enter to accept the default file name for the key.
    4. Enter a passphrase and then confirm it.
    5. The utility will display the location of your public key. If you accepted the default location, that is the following in Windows: C:\Users\(UserName)/.ssh/id_rsa.pub.
    6. Open the public key file with a text editor. Copy the the contents. 
  2. Add the SSH Key to Github
    1. Open Github.com
    2. Click on the profile icon
    3. Choose Settings
    4. Select the "SSH and GPG Keys" tab
    5. Click "New SSH Key"
    6. Enter a title in the "Title" field. For example, "My Work Computer"
    7. Paste the SSH Key string into the "Key" field. (This string comes from the last part of "Generate a new SSH Key on your PC").
    8. Click the "Add SSH Key" button

Instructions to Start Tracking a New Module

Install One Network's Software Development Kit (SDK)

  1. Download and install Java Developer Kit 12 on your computer.
  2. Open a new web browser tab. Navigate to: https://www.onenetwork.com/dev-net/developer-resource-center/

  3. Register for a developer account and log in.

  4. Scroll down and click Register for a Free Account Now or Register at: https://esg.onenetwork.com/onboard?svcId=1003

  5. Click on the link labelled "SDK_23.0.exe“ to download the Software Development Kit.

  6. When the download finishes, click the file to start the installation process.

  7. Follow the installation prompts.

    1. Note: During the installation of the ONE SDK, you will be prompted to installed Oracle XE. This database is used by the platform.

Start the SDK

  1. In the Windows Start menu, go to One Network SDK NEO 3.0
  2. Select One Network Studio 3.0

Create a new Module and Dataset

  1. Select File from the main menu
  2. Choose New → Platform Module
  3. Enter basic module details:
    1. Module Name
      1. Enter "GithubTest".
    2. Source Code Package
      1. Enter "com.onenetwork.githubtest".
    3. Request Module Prefix
      1. Enter "GITH" or some other unique 4 letter combination.
    4. Platform Location
      1. This will default to: C:\OneSDK_NEO3.0\default-instance\platform
      2. Leave it at this value.
    5. Initial Module Version
      1. This will default to: 1.0
      2. Leave it at this value.
    6. Create sample dataset
      1. This will default to checked.
      2. Leave this checked.
    7. Value Chain ID
      1. This will default to a unique number. 
      2. If you are a One Network enterprise customer, then enter your Value Chain ID here. Otherwise, leave it at the default value.
    8. Module Location
      1. This will default to: C:\OneSDK_NEO3.0\modules
      2. Leave it at this value.
    9. Click Finish
      1. Your new module will appear at this location:
        1. C:\OneSDK_NEO3.0\modules\GithubTest
      2. Your new dataset will appear at this location:
        1. C:\OneSDK_NEO3.0\modules\GithubTest_dataset

Create a Git Repository in Github

  1. Log into Github.com.
  2. Click New next to Repositories.
  3. Complete the Create a new repository prompts
    1. Repository name
      1. Enter "ONEGithubTest".
    2. Description
      1. Enter "This is a test of tracking module development with Github."
    3. Public / Private
      1. Select Private.
    4. Initialize this repository with a README
      1. Uncheck this.
    5. Add .gitignore
      1. This will default to None.
      2. Leave this at the default.
    6. Add a license
      1. This will default to None.
      2. Leave this at the default.
  4. Click Create repository.

Initialize and Commit Your Local Repository

  1. Open the command prompt.
  2. Change directory to the location of your module 
    1. For example: cd C:\OneSDK_NEO3.0\modules\GithubTest
  3. Run: git init
    1. This initializes an empty git repository.
  4. Run: git remote add origin git@github.com:mnutsch/ONEGithubTest.git
    1. This will connect your local git repository to the Github repository.
  5. Create a file named .gitignore
    1. From the Windows command prompt, you can do this with: echo.>.gitignore
  6. Edit .gitignore 
    1. Open the .gitignore file in a text editor. 
    2. Add these lines:
      1. /build/*
        1. This tells Git to ignore generated Build files.
        2. We don't want to track these, because they change frequently and are generated from the source.
      2. /build-eclipse/*
        1. This tells Git to ignore Studio related generated Build files.
        2. We don't want to track these, because they change frequently and are temporary.
      3. local.properties
        1. This tells Git to ignore the file "local.properties"
        2. We don't want to track this file, because it has sensitive information in it. 
    3. Save the changes.
  7. Create a file named readme.md
    1. From the Windows command prompt, you can do this with: echo.>readme.md
  8. Edit readme.md
    1. Open the readme.md file in a text editor. 
    2. Add a description of your module. For now, put something simple like: "# ONE Module Github Test"
    3. This ReadMe file gets displayed when somebody views the repo in Github.
    4. The format of this file should be Markdown.
      1. A good example of Markdown formatting can be found here: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
    5. Save the changes.
  9. In the command prompt, from the module folder, run: git status
    1. This will list all of the files in the folder.
    2. They are color coded to tell you if they are being tracked by version control. Right now they are all red, because nothing is being tracked yet.
  10. Run: git add .
    1. This will add all of the files in the directory, except for those that the .gitignore specifies to ignore.
  11. Run: git commit -am "First commit."
    1. The text in quotes is the message that will be tagged with your source code commit.
    2. Usually you will want to include this with a short description of the changes that you made. 
    3. If you use an issue/project tracking tool like Jira, then it is customary to include the ticket number in the description as well.
  12. Run: git push -u origin master
    1. This will push your module to the git repository. 
    2. If you refresh the Github repository in your browser, then you will now see the files from your module.

Note: These steps only initiated tracking of the Module. You will want to follow the steps again to set up a repo for tracking changes to the Dataset.

Special Note about React UI Pages and .gitignore

If you are using the NEO 3.0 version of the SDK and also working with React UI pages, then you will want to add extra lines to the .gitignore file.

  • web/react-modules/myReactPageName/node_modules/*
  • web/react-modules/myReactPageName/package-lock.json.installed
  • web/react-modules/myReactPageName/package-lock.json
  • web/react-modules/myReactPageName/.*/

Instance Spec Files

For loading One Network software we use a ".spec" file. This file tells our Instance Builder script where to get modules to include in an app. 

The following are Git specific attributes for "app" elements in the Instance Builder .spec files:

  • local = (Required) This is the intended local path for the Module or Dataset. For example "apps/GithubTest2".
  • gitRepo = (Required) This is the clone URL for the Git repo. For example "git@github.com:mnutsch/ONEGithubTest.git". Note: If "gitRepo" is present, then "repo" should NOT be present.
  • gitBranch = (Optional) This is desired the branch of the Git repository. For example "secondBranch".
  • gitCommit = (Optional) This is the desired commit of the Git repository. For example "d8cb595".
  • gitTag = (Optional) This is the desired tag of the Git repository. For example "23.0". Note: using gitTag will result in the module being loaded in a "headless" state. In order to begin committing changes, you will want to first checkout a branch.

This is an example of what a basic Instance Builder spec file configured to pull a module from Github:

<?xml version="1.0" encoding="UTF-8"?>
<instancespec instance="SCC 13.0" version="latest">
<platform branch="23.0-rb" changelist="latest" ibVersion="23.0-rb"/>
<app local="apps/GithubTest2" gitRepo="git@github.com:mnutsch/ONEGithubTest.git" gitBranch="secondBranch" gitCommit="d8cb595"/>
</instancespec>

Note: In order to pull modules from a private Git repo, you need to have a non-password protected SSH key as described above under "Set up a SSH Key for Authenticating..." above.