random-ideas.md

Contributing to SageMathCloud (SMC)

NOTE: this is a rough markdown file to collect ideas. Once this is thought through I'll make a polished slideshow out of it. So don't worry about formatting or wording if you look at this!

Length: 55 minutes

(2 min) Introduction

Goal of talk: Explain how to work on SageMathCloud.

Problem: I do around 95% of SMC development:

> git log |grep Author |wc -l
9763
> git log |grep "Author: William Stein" |wc -l
9340

Detailed line-by-line-git-blame-style summary of the current code, in case one wants to be pedantic in blame.txt.

(2 min) What is SMC?

• Launch: I launched SMC in April 2013.

• Size: SMC runs on dozens of VM's on Google compute engine. 250K projects made. Over 30K monthly active users. Over 850 simultaneous users.

• Features: realtime collaboration, LaTeX editing, Sage worksheets, R, Jupyter notebooks, color terminals, write Fortran/C/C++/Java/Haskell/etc. programs, todo lists, course management, chatrooms.

• Devel: SMC can also now be run in a new single-user developer-friendly mode.

(3 min) The SMC Tech stack

• Node.js - javascript on server side; amazing ecosystem

• CoffeeScript - Javascript preparser -- no braces and semicolons

• Engine.io/Primus - websockets + fallback

• React.js - sane declarative rendering and mutating of UI

• RethinkDB - scalable, replicated database that pushes changes (=nosql db + message queue)

• SageMath - the real power

• Jupyter Notebook - interactive coding

• Webpack - bundles all assets of webpage

• LaTeX - math typesetting: both backend in linux and mathjax on frontend

(3 min) Contributing to SMC

• Use Github: https://github.com/sagemathinc/smc

• SMC dev: (1) in an SMC project, (2) on Linux/OS X

• License: GPLv3+ compatible.

(15 min) Tutorial -- part 1: setup SMC dev environment

1. (2 min) Create a project and increase memory to 2GB!

2. (3 min) Open a terminal and clone the repo:

    git clone https://github.com/sagemathinc/smc
   

Right now you must checkout the smc-in-smc branch!: cd smc/; git checkout smc-in-smc

3. (8 min) Build/install everything:

    cd ~/smc/src; . smc-env; npm run make
   

4. (2 min) Start everything:

    cd ~/smc/src/dev/project; ./tmux-start-all
   

NOTE: ./tmux-start-all uses http://tmux.github.io/; you can instead run the ./start- scripts...

NOTE: The first time after everything starts up, you might have to stop it all and start it again. The hub websocket server may not properly initialize the first time, when the database takes a long time to get configured.

NOTE: For devel on a laptop, you must also (1) install node.js v5.0 and RethinkdDB, and (2) do cd dev/laptop; ./tmux-start-all

Installing node.js 5.x on Ubuntu:

> wget -O -  https://deb.nodesource.com/setup_5.x | sudo -E bash -
> sudo apt-get install nodejs

Random Ports: If somebody steals a port from you, delete ~/smc/src/dev/project/ports and start everything again. This is unlikely, but could happen.

BUGS: (that I will fix soon)

• The first time you open a new project you will get an error "Directory listing error". Try again.

• Latex, Jupyter, and anything else that uses "the raw server" doesn't work yet.

• On a laptop, you must do pip install smc_pyutil still.

(30 min) Tutorial -- part 2: exercises

(6 min) change frontend UI: Help: "Support --> Random links"

Edit smc-webapp/r_help.cjsx...

• Open smc/src/smc-webapp/r_help.cjsx

• Change "Support" to "Random links"

• When you save, webpack will update

• Refresh help page and see change (react hot loader not implemented in SMC yet)

(6 min) change backend hub: "When creating account, change user's name to Mom"

Edit smc-hub/hub.coffee...

• Open smc/src/smc-hub/hub.coffee

• Note that it is way too big and needs to be refactored

• Find the function create_account

• Add this code: mesg.first_name = "Super"; mesg.last_name = "Mom"

• Stop the hub and start it again: (1) use tmux to get to the hub log, hit control+c to stop it. (2) start it again in a separate terminal session, make new account, verify result.

(6 min) change local hub: "When opening a file, put 'HI MOM!' at the top."

Edit smc-project/local_hub.coffee...

• Open smc/src/smc-project/local_hub.coffee

• Look for lines involving fs.readFile, and find @init(doc:data.toString().replace(/\r/g,''), id:"file_server")

• Change it to @init(doc:'Hi Mom!\n' + data.toString().replace(/\r/g,''), id:"file_server")

• Create a project and open it (NOTE caveat that have to refresh!)

• Open a file

(6 min) change console server: "Write 'HI MOM!' to terminal stream whenever opened"

Edit smc-project/console_server_child.coffee...

• Open smc/src/smc-project/console_server_child.coffee

• Put this line at the bottom: socket.write("HI MOM!\n")

• Open a terminal (restart project if you had already opened a terminal!). Maybe hit return a few times. See "HI MOM!".

(6 min) change sage server: "Predefine an extra variable in Sage worksheets called MOM."

Edit smc_sagews/smc_sagews/sage_server.py...

• Open smc/src/smc_sagews/smc_sagews/sage_server.py

• Search in the file for __SAGEWS__

• Add this line after it: namespace['MOM'] = "hi there!"

• (TEMPORARY-BUG) Install sage_server code: pip install --user /projects/[your project id]/smc/src/smc_sagews/

• Open a sage worksheet and type MOM (shift+enter) and see if it worked. (If it didn't, restart your sage server.)