Susereum Developer's Guide
Susereum is a software system that aids software projects towards more sustainable code. This is accomplished by developers/contributors of a project, agreeing and enforcing a set of code standards that are designed to prevent future code smells.
Susereum keeps track of all agreements and records throughout the project’s lifecycle with blockchain. Susereum also evaluates that a project’'s metadata is meeting these set standards.
GitHub is the best place to store records for every unique individual project throughout its entire lifecycle. The following records will be found in every project: set of health measures, project health evaluation reports, proposal history, and project contributors.
-
Ubuntu 16.04
-
Python 2.7
-
Python 3.5 or higher
-
Git
-
SourceMeter
-
For information on how to install SourceMeter, please refer to the Developing Susereum for Personal Use section.
-
For more information on SourceMeter product, please refer to How Susereum Achieves Sustainable Code page which can be located in the Code Analysis section.
-
-
Sawtooth
-
Susereum is required to be run on blockchain. Use the following link on how to install the components of Sawtooth on Ubuntu 16: How to install Sawtooth
-
Alternatively, you can set up sawtooth using the following video link: Setting up Sawtooth on Ubuntu 16.04
-
For more details regarding the internal functions of the blockchain, you can consult the official documentation of Hyperledger Sawtooth
-
| Python Module | Required Libraries |
|---|---|
| GitHub | toml, requests |
| Sawtooth | toml, yaml |
| Code Analysis | pandas |
| GUI | Gtk 3.0, PyGObject, requests, matplotlib |
Note: script "install.sh" under ServerSideScripts can run on Ubuntu to install the required libraries
For developers who wish to modify or view the code base for Susereum can do so on their system/machine by cloning the following GitHub link and do the following steps:
- Use the Command Prompt/Terminal/your favorite Python Editor to clone or download the Susereum Repository by using the following link:
https://github.com/obahy/Susereum.git
- Once you clone the repository, you will need to run the install script
cd Susereum/ServerSideScripts/
sudo ./install.sh
-
Download SourcerMeter using this link
- You will need to enter a valid email where this is where your downloadable .zip or .tar file will be sent.
- For more information on SourceMeter, please refer to How Susereum Achieves Sustainable Code page which is located in the Code Analysis section
-
Unzip SourceMeter into Susereum/CodeAnalysis/SourceMeter_Interface/
-
Now have access to all Susereum’s project files. These include GTK+, GUI application using the PyGObject:
-
Locate the login script which can be found under, “Susereum-master/GUI/login_screen.py”. Run the script and enter your GitHub credentials.
- In order to upload your GitHub repository to Susereum, go to the GitHub repository where Susereum has been installed and view the Config (.suse) file which should look like the following:
# Copyright 2017 Intel Corporation
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# ------------------------------------------------------------------------------
#
# Sawtooth -- Settings Transaction Processor Configuration
#
[about]
NewuserLink = "http://Some.IP.Address./connect/tmp.<fileID>"
Title = "Code Smell Family Configuration"
[vote_setting]
proposal_active_days = 3
approval_treshold = 1
[code_smells.method]
SmallMethod = [ 5, 1,]
LargeParameterList = [ 5, 1,]
LargeMethod = [ 50, 1,]
[code_smells.comments]
CommentsToCodeRatioUpper = [ 35.0, 1.0,]
CommentsToCodeRatioLower = [ 10.0, 1.0,]
[code_smells.class]
SmallClass = [ 10, 1,]
GodClass = [ 5, 1,]
LargeClass = [ 100, 1,]
InappropriateIntimacy = [ 5, 1,]
- Use copy the 'NewUserLink' to Susereum so your project can be analyzed. For More information regarding the GUI, please refer to the GUI Module and Helpful Links Module found later in this guide.
Note: The config file ".suse" in you project is written in "TOML"
If you are planning to get familiar with the codebase and developing on the Susereum product, please read the upcoming sections.
Information regarding Susereum Architecture: Susereum Architecture
Information regarding how Susereum achieves sustainable code: How Susereum Achieves Sustainable Code
The following steps will guide throughout the process of getting the necessary components to contribute to the Development of Susereum. The first component that we will address is the GitHub Module and its components. Next, we will discuss the Sawtooth Blockchain module.
To get up and running with the GitHub ModuleScript, one can view the following video (provided its dependencies are installed form the Requirements Section):
Video: Running Suseruem Scripts on your Local Machine/Device
Alternatively, developers can use the upcoming section on how to set up and run the GitHub ModuleScript.
You will need to run the server from two different terminals. The first one is for the proxy to connect to the server, and the other is for the server listening in the proxy.
In the Susereum’'s Github App Settings, you will notice the Homepage URL and Webhook URL have a smee URL. Note: Please keep in mind if you want to run the server out of campus please use a VPN to connect to UTEP’s 's IP address.
On your terminal/command prompt SSH command into the server by entering:
ssh <server_user_id>\@<use.your.IP.address>
password:<yourpassword>
If it is your first-time logging into the server, you will be asked if you want to accept the connection please type Yes. You will only have to do this once on your computer.
You should get the following output:
Using the previous steps on the same terminal from “Start Team Viewer Server" Section.
First, navigate your current path to Desktop/Github.
Install:
npm install --global smee-client
Run the client:
smee -u https://smee.io/XviEAcJZCaJ9jnW
You should get the following output:
Forwarding https://smee.io/XviEAcJZCaJ9jnW to http://127.0.0.1:3000/
Connected https://smee.io/XviEAcJZCaJ9jnW
The proxy is now running, leave this in the background.
Now, open another terminal/command prompt and ssh, in the same way, mentioned “"Starting the Server Section”" and navigate to the same directory. (Connect to the server once again).
Now you need to enter some environment variables. You may want to save these in a text file somewhere in your computer for easy access.
Enter the following commands:
export GITHUB\_APP\_IDENTIFIER=<appid>
Note: the ID can be found in the About section of the GitHub App general settings page
export GITHUB_WEBHOOK_SECRET="<yoursecret>" -->
export GITHUB_PRIVATE_KEY=`awk '{printf "%s\\n", $0}' <your_private_key>.pem`
Note: Don’'t forget that backtick at the end of .pem` and that you are at the path of where your private path key file is stored.
To make sure your environment variables are set up correctly you can enter the following command:
env
A list of your local environment variables will be displayed.
If your key was stored correctly you should have something similar to this:
GITHUB\_PRIVATE\_KEY=
--------BEGIN RSA PRIVATE KEY----------
Blah blah blah key stuff
--------END RSA PRIVATE KEY----------
Now anytime somebody pushes to the SampleProject1 and SampleProject2 repositories, that gitApiListener.py should run.
Type the following:
python <scriptname.py> 3000
Note: We write 3000 since our proxy is on port 3000
We are going to test if the gitApiListener python script we just ran in the previous section is actually listening for changes done to any project found in Susereum ‘s repositories. Important: To test this, you must be a collaborator or owner to the project you are pushing to.
- Clone a project with Susereum installed
- In a new terminal enter:
git clone https://github.com/susereum/SampleProject1.git
- In a new terminal enter:
- Make a change to the project
- Edit any of the files in the repository, create a new file, or delete a file (except for the SuseMeasures.suse file which is required for code analysis)
- Push your changes
- Add all of your changes to be prepared to commit
git add -A - Create the commit with a message
git commit -m "I'm making a change" - Push that commit to GitHub (it may prompt you to authenticate your GitHub account)
git push
- Add all of your changes to be prepared to commit
Now, look back at those terminals/command prompts wherethat you ran the smee proxy and python GitHub listening script in, you should start seeing some activity.
On the Smee proxy terminal:
On the GitHub script terminal:
- SSH into the Susereum server
<server_user_id>\@<use.your.IP.address> - Navigate to the script
cd ~/Desktop/Github - Edit the script. There are multiple methods of editing the script, including
nano,vim,emacs, etc. We will assume the developer is familiar with vim.vim gitApiListener.py
Please see https://developer.github.com/v3/activity/events/types/ for a list of webhook events that may be subscribed to and their associated payloads.
Note: From the Building Your First GitHub App tutorial, the script is originally written in Ruby. This is because GitHub is written in Ruby, and their Octokit library is for Ruby scripts. The Susereum GitHub script uses Python for consistency with the rest of the project and the current developers prefer it. Therefore, the script contains extra functions that validate webhook events received from GitHub, and authenticate requests to GitHub to change or create new files.
If you have already installed sawtooth using the links provided in the Requirements Section, Please ignore this module. If you have not yet installed sawtooth, please use the following links:
Susereum's Developers can use the command line interface of each processor family to test and validate their changes. Details of all command line interfaces can be found at: CLI Command Reference
More information regarding sawtooth installation and components can be found in Sawtooth Documentation: Sawtooth Documentation
For more information on how to use the GUI, please see Helpful Links at the bottom of this page.
Susereum GUI is developed using GIMP Toolkit (a.k.a GTK). GTK is a multi-platform toolkit for creating graphical user interfaces. GTK supports wide range of languages including Python and Java.
For this particular project, we have used GTK 3.0. More information about GTK can be found on Gtk.org
Since we have used Ubuntu as the primary OS for Susereum development, the steps to install the GUI dependencies are as follows:
sudo apt-get -y install python bash
sudo apt-get -y install python-pip python-dev build-essential
sudo pip install --upgrade pip
sudo pip install --upgrade virtualenv
bash
sudo apt-get install libgtk-3-dev
sudo apt install libgirepository1.0-dev
sudo pip install toml
sudo pip install matplotlib
sudo pip install requests
Add the screens and explain a little about them.
You should get the following output:
Note: If you are not on the UTEP campus, please connect using a UTEP's VPN
As of now, Susereum is not a public application, it is only available to the owner and current contributors. For this reason, a new GitHub account was created specifically for Susereum. To access the developer's contents and the credentials to access the account, use the following link:
To edit the GitHub App settings, you log in to the Susereum GitHub account, click the user icon in the top-right corner / settings / Developer settings / GitHub Apps and click Edit beside the Susereum app.
In the Susereum GitHub app, you can specify what permissions, and events you want GitHub to notify you in your application. Below is a screenshot of some permissions that be activated.
Below is a list of Susereum's current permissions and events:
| Permissions Name | Access Level |
|---|---|
| Repository Contents | Read and Write |
| Repository Metadata | Read |
| Push | Subscribed to event |
One reason you might go into these settings is to install it on another sample repository by going to the Install App, clicking the Cog, choosing Only select repositories and then selecting any Susereum GitHub account’'s repositories.
You might also want to publish this app to the GitHub marketplace for any project to install by going to Advanced and Make public.
Note: Anytime permissions are changed, all owners of repositories with Susereum installed will receive an email asking if they agree to Susereum’'s proposed permission changes. Until they accept the changes, Susereum can NOT listen to those events.
Here are some helpful links that will help you navigate through the Susereum product:
Videos on how to: