Hello World¶

Owner(s): Phil Marshall (@drphilmarshall), Greg Madejski (@Madejski)
Maintainer(s): Alex Drlica-Wagner (@kadrlica)
Last Verified to Run: 2021-03-31
Verified Stack Release: 21.0.0

Learning Objectives:¶

After working through this tutorial you should be able to:

1. Edit a notebook in the JupyterLab environment
2. Commit and push those changes back to a development branch, having learned the Stack Club git/GitHub workflow.

Logistics¶

This notebook is intended to be runnable on lsst-lsp-stable.ncsa.illinois.edu from a local git clone of https://github.com/LSSTScienceCollaborations/StackClub.

Set-up¶

You need to be looking at this notebook from within an LSST JupyterLab instance. If you are, that means you have successfully started a JupyterLab instance, but have also managed to clone the StackClub repo into the notebooks folder. If you have not done this yet, please follow the "Getting Started" instructions here.

Start a terminal via the Launcher (go to the menu on top, "File" > "New Launcher"), and cd notebooks/StackClub. Then, make sure you are in a development branch. You can make a new one with, for example,

git checkout -b issue#11-hello-world-gmm

But of course the argument of this git checkout -b command will be different - you can name your local branch whatever you like.

You might need to make sure to check for the existence of the branch. If you issue the command and the branch exists, you will get a message like "fatal: A branch namedissue#11_hello-world-gmm already exists." Use git branch to see your available local branches, and git pull to track all remote branches.

Also please make sure that you are using the correct version of python ("LSST"); this might be obvious to some, but editing / running the same notebook with different versions of python can cause problems.

Editing this Notebook¶

You edit a notebook "entry by entry" or more correctly "cell by cell." To start editing an entry, step to it - a blue bar will appear on the left of the entry. Cells can be "Markdown" (like this one), "Raw", or "Code" (executable python).

The next cell after this one is a python cell, defining a function that you may or may not find useful. When you execute that cell (pro-tip: hit "shift+enter"), the function is loaded for later use; the following cell calls that function. Give it a try.

take_that_first_baby_step()

Here is an example task for real newbies: add a single code or markdown cell at the end of this notebook, with a suitable message for the ages, including some sort of signature. This will make you famous, once you commit and push.

Contributing Your Work¶

Now that you have improved this Notebook, you need to ask for your work to be included into the Stack Club library of community tutorials. Here's the recommended workflow:

1. Check that this notebook runs without errors and clean out the outputs.
2. Commit your changes to a development branch
3. Push your commits to a branch of the same name to the origin repo at GitHub.com
4. On the GitHub web interface, submit a Pull Request to the master branch

1. Checking the Notebook¶

From the menu bar, do:

Kernel -> Restart and Run All Cells

Then, if that worked OK, clean up the Notebook with

Kernel -> Restart and Clear All Outputs

The Notebook is now ready to commit. Hit "save" in the notebook editor to make sure your edits are captured.

2. Committing Your Changes¶

Just in case, make sure you are on a development branch with a git status in the terminal tab. If not, make one with something like this:

git checkout -b issue#11_Hello_World_gmm

You may not be responding to an issue, so might want to name your branch differently. Here's an example history:

[drphilmarshall@jld-lab-drphilmarshall-r150 StackClub]$ git checkout -b issue#11_Hello_World_gmm
M       notebooks/Hello_World.ipynb
Switched to a new branch 'issue#11_Hello_World_gmm'
[drphilmarshall@jld-lab-drphilmarshall-r150 StackClub]$ git status
On branch issue#11_Hello_World_gmm
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        modified:   notebooks/HelloWorld.ipynb

no changes added to commit (use "git add" and/or "git commit -a")

Now you are ready to commit, like this:

[drphilmarshall@jld-lab-drphilmarshall-r150 StackClub]$ git commit -am "Notes on how to edit the Notebook"
[issue/11/hello-world-pjm 140240c] Notes on how to edit the Notebook
 1 file changed, 193 insertions(+), 250 deletions(-)
 rewrite notebooks/HelloWorld.ipynb (63%)

You might be asked by git to provide info about yourself. If so, you will need to provide your e-mail address as well as your git username: you need to provide both.

3. Pushing Your Commits¶

Push to a corresponding branch on GitHub. Stack Club members have Write access to the base repo, so can push there. Others, you'll need to first fork the StackClub repo, and then push to your fork. Here's an example history for an earlier version of a "HelloWorld" notebook:

[drphilmarshall@jld-lab-drphilmarshall-r150 StackClub]$ git push origin issue/11/hello-world-pjm
Counting objects: 4, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (4/4), 2.03 KiB | 0 bytes/s, done.
Total 4 (delta 1), reused 0 (delta 0)
remote: Resolving deltas: 100% (1/1), completed with 1 local object.
To github.com:LSSTScienceCollaborations/StackClub.git
 * [new branch]      issue/11/hello-world-pjm -> issue/11/hello-world-pjm

4. Submitting a Pull Request¶

The master branch is protected, to a) make sure we review our code and b) enable continuous integration and testing via travis-ci.

Don't forget, when you click the big green "Submit Pull Request" button, it will send an email to everyone watching the repo (as well as anyone else you mention). It's your chance to ask for club code review, so make sure the PR title (email subject line) and comment (email body) are well-formed.

Further Edits to this Notebook¶

Here's where you should make your mark. Have fun!