IDE Getting Started Guide

Author: Amin Shali, amshali@google.com

This document intends to help developers get started with the Codiad IDE.

Accessing the IDE

Workspace Layout

Responding to review comments

Once your change is approved

Previewing files and running apps inside IDE

Codiad IDE is a Google Cloud based IDE running on top of managed VMs. It is part of developer tools bundle which also contains Jenkins and Phabricator. IDE currently integrates with Phabricator for requesting code reviews (and in the near future for viewing and responding to the review comments). IDE has not integrated with Jenkins yet.

Prerequisite

This document assumes that you have already setup the developer tools bundle.

Accessing the IDE

After a successful setup, navigate to the IDE at the following url:

https://codiad-dot-<your-project>.appspot.com

IDE uses appengine authentication to make sure you are a member of the project. If you are not you can request access.

Note: Sometimes when the IDE has just been deployed, it will try to pull some docker images and synchronizing workspaces. This may take a few minutes. Just wait and you will be automatically connected to IDE once it is up and running.

Workspace Layout

By default you will see a project created for you in your workspace. The project is called “Cloud Project”. You can start editing in this project or you can create your own project. The layout of workspace is shown in the following figure:

The workspace layout

Adding a New Project

You can add two kinds of projects. File System Projects and projects created from Git repositories. In order to add any project Select Create project from Workspace menu.

Create a Project

File System Project

A file system project is simply a directory on your workspace which you can start any project from scratch in there.

Create a file system project

We suggest using a project name and path which does not contains “/”.

Git Project

You can create git project from any git repository as long as it does not require username and password.

Create project from git repository

You can clone the git repository of your Google cloud project simply by pointing to the repository clone URL found in your cloud console. This must be the source repository of the project on which you have installed the IDE(or bundle).

If you want to add a different Google cloud project, you must add the IDE service account as an editor to that cloud project and then you can clone its repository.

IDE Terminal

In order to accomplish some of the tasks during development, one might need to have access to a terminal. The IDE provides a terminal which is running on the IDE container. It will allow you to do pretty much anything you want to do on a regular Linux machine. In order to access this terminal click on the handlebar at the bottom of the IDE.

Important Note: By default we are running a tmux session as soon as you open the terminal. The appengine connection drops from time to time and will cause the terminal to go away. A tmux session will help you preserve your ongoing work in the terminal.

This terminal is especially useful for executing git commands. Note: When a git branch is merged, the code review in Phabricator is automatically marked closed.

File Editor

IDE provides CodeMirror (http://codemirror.net/) for editing files. CodeMirror supports syntax highlighting for more than 100 languages.

Editor Screenshot

Some of the major functions that editor offers are:

Find: Ctrl + F
Find and Replace: Shift + Ctrl + F
Word Completion: Ctrl + Space
Save: Ctrl + S
Undo: Ctrl + Z
Redo: Ctrl + Shift + Z

You can find other shortcuts under Edit, Search and Navigate menus.

Editor Settings

Editor can be configured at the level of your whole workspace. The configurations can be found under Settings. You can access Settings in the bottom bar as shown in the following figure:

Settings

The following dialog will show up in which you can change the editor settings and save them. In this dialog you can also configure the file explorer behavior in addition to the file extensions.

Reviews

When IDE is bundled up with a phabricator instance, it can show the reviews of your current branch. In order to access the reviews, open up the review panel by clicking on the handlebar at the top right side of the IDE.

The code review panel has a button at the top for loading the reviews. Each thread of comments is shown along with the ~10 lines of code context.

Sending a Review

Once you have a changelist ready for review you can send a code review from IDE. In order to do so, you must use Terminal window to send your code review. Follow these instructions to do so:

Development

Make sure that you always create a git branch from the master branch before you start editing the code.
Make sure that your master branch is always in sync with origin master before merging and creating branches.
It is highly recommended to start your dev branch with your ldap followed by a “/” and then a short name describing what the branch is.
Commit often.

$ git checkout master

$ git pull origin master

$ git checkout -b amshali/fix-copy-paste-issue

## edit edit edit….

## Make sure you add untracked files using git add

$ git commit -am “My glorious changes”

Requesting a review

Make sure you have already synced the master branch and have merged with it:

$ git checkout master
$ git pull origin master
$ git checkout amshali/fix-copy-paste-issue
## You might have to take care of merge conflicts sometimes.

## Hopefully not a lot.
$ git merge master
$ git add untracked_files
$ git commit -am “My awesome fix”
$ git appraise pull

## reviewers=“userid1,userid2,...”
$ git appraise request -r $reviewers -m $message
$ git appraise push
$ git push origin amshali/fix-copy-paste-issue

Responding to review comments

Edit the code to make sure you have addressed all the comments. Do the following to send a revision back:

$ git commit -am “Fix to my glorious changes”
$ git checkout master
$ git pull origin master
$ git checkout amshali/fix-copy-paste-issue
$ git merge master
## You might have to take care of merge conflicts sometimes. Hopefully not a lot.
$ git push origin amshali/fix-copy-paste-issue

You can also respond to review comments through the command line using

$ git appraise comment -m “<comment>” <file name> <line number>
$ git push

Once your change is approved

Congratulations!

$ git commit -am “Little stuff I addressed”
$ git checkout master
$ git pull origin master
$ git checkout amshali/fix-copy-paste-issue
$ git merge master
## You might have to take care of merge conflicts sometimes.
$ git push origin amshali/fix-copy-paste-issue
$ git appraise pull
# next line will merge the changes back into master,
# and change your branch back to master
$ git appraise submit
# now push those changes up to the origin:
$ git push origin master
## Done!

Previewing files and running apps inside IDE

If you have an HTML file or Javascript file which you would like to try out and preview during the development process you can easily do that by right clicking on the file in the file browser and click on “Preview”. That will enable you to essentially preview any file inside your browser. If your HTML file requires to include some Javascript or CSS file simply include those in your HTML file using a relative path.

It is also possible to run any server inside the IDE and interact with it. For example let’s say we have a simple nodejs express server as follows:

var express = require('express');

var app = express();

app.get('/', function (req, res) {

res.send('Hello World!');

});

var server = app.listen(10000, function () {

var host = server.address().address;

var port = server.address().port;

console.log('Example app listening at http://%s:%s', host, port);

});

This is a simple nodejs/express hello world server. Please notice that this server is running on port 10000. After running this hello world server you can access it using the following URL:

https://codiad-dot-<your-project>.appspot.com/p/10000/

Note: Right now we have three ports open to use inside IDE. Those are 10000, 10001 and 10002.