adding fork me on github, page on environment metadata, and making to…

…ns of changes for 2.3!
cyphar · Apr 10, 2017 · dfba702 · dfba702
1 parent b48dc0e
commit dfba702
Show file tree

Hide file tree

Showing 20 changed files with 775 additions and 386 deletions.
diff --git a/_data/sidebars/user_docs.yml b/_data/sidebars/user_docs.yml
@@ -31,6 +31,10 @@ entries:
       url: /docs-mount
       output: web, pdf
 
+    - title: Environment and Metadata
+      url: /docs-environment-metadata
+      output: web, pdf
+
     - title: Change an Existing Container
       url: /docs-changing-containers
       output: web, pdf

diff --git a/_includes/github_banner.html b/_includes/github_banner.html
@@ -0,0 +1,6 @@
+<img id="forky" style="position: absolute; top: 0; right: 0; border: 0; z-index:1050; cursor:pointer" src="https://camo.githubusercontent.com/38ef81f8aca64bb9a64448d0d70f1308ef5341ab/68747470733a2f2f73332e616d617a6f6e6177732e636f6d2f6769746875622f726962626f6e732f666f726b6d655f72696768745f6461726b626c75655f3132313632312e706e67" alt="Fork me on GitHub" data-canonical-src="https://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png">
+<script>
+$("#forky").click(function(){
+  window.open("https://github.com/singularityware/singularity");
+})
+</script>
diff --git a/_layouts/default.html b/_layouts/default.html
@@ -1,6 +1,7 @@
 <!DOCTYPE html>
 <head>
     {% include head.html %}
+    {% include github_banner.html %}
     <script>
         $(document).ready(function() {
 

diff --git a/assets/img/diagram/singularity-2.3-flow.png b/assets/img/diagram/singularity-2.3-flow.png
diff --git a/index.md b/index.md
@@ -6,13 +6,12 @@ permalink: index.html
 toc: false
 ---
 
-Singularity enables users to have full control of their environment. This means that a non-privileged user can "swap out" the operating system on the host for one they control. So if the host system is running RHEL6 but your application runs in Ubuntu, you can create an Ubuntu image, install your applications into that image, copy the image to another host, and run your application on that host in it's native Ubuntu environment!
+Singularity enables users to have full control of their environment. Singularity containers can be used to package entire scientific workflows, software and libraries, and even data. This means that you don't have to ask your cluster admin to install anything for you - you can put it in a Singularity container and run. Did you already invest in Docker? The Singularity software can import your Docker images without having Docker installed or being a superuser. Need to share your code? Put it in a Singularity container and your collaborator won't have to go through the pain of installing missing dependencies. Do you need to run a different operating system entirely? You can "swap out" the operating system on your host for a different one within a Singularity container. As the user, you are in control of the extent to which your container interacts with its host. There can be seamless integration, or little to no communication at all. What does your workflow look like?
 
 
-<a target="_blank" class="btn btn-primary navbar-btn cursorNorm" role="button" href="https://goo.gl/forms/D7ed1dfLeNvml6no1">Register your Cluster</a> <a target="_blank" href="https://goo.gl/forms/tGBKnKwplNyRZRSm2" class="btn btn-primary navbar-btn cursorNorm" role="button">Add a Publication</a>
-
+<img style="max-width:900px" src="/assets/img/diagram/singularity-2.3-flow.png">
 
-Singularity also allows you to leverage the resources of whatever host you are on. This includes HPC interconnects, resource managers, file systems, GPUs and/or accelerators, etc. Singularity does this by enabling several key facets:
+It's pretty simple. You can make and customize containers locally, and then run them on your shared resource. As of version 2.3, you can even import Docker image content without sudo permissions. Singularity also allows you to leverage the resources of whatever host you are on. This includes HPC interconnects, resource managers, file systems, GPUs and/or accelerators, etc. Singularity does this by enabling several key facets:
 
 * Encapsulation of the environment
 * Containers are image based
@@ -21,7 +20,10 @@ Singularity also allows you to leverage the resources of whatever host you are o
 
 ## Getting started
 
-Jump in and <a href="/quickstart"><strong>get started</strong></a>.
+Jump in and <a href="/quickstart"><strong>get started</strong></a>. Have a publication or recently installed or updated Singularity on your cluster? Please tell us about it!
+
+<a target="_blank" class="btn btn-primary navbar-btn cursorNorm" role="button" href="https://goo.gl/forms/D7ed1dfLeNvml6no1">Register your Cluster</a> <a target="_blank" href="https://goo.gl/forms/tGBKnKwplNyRZRSm2" class="btn btn-primary navbar-btn cursorNorm" role="button">Add a Publication</a>
+
 
 <hr style="margin-top:20px">
 

diff --git a/pages/docs/contributing/contributing-code.md b/pages/docs/contributing/contributing-code.md
@@ -14,6 +14,10 @@ To contribute to the development of Singularity, you must:
 - Read, understand and agree to the license
 - Have a GitHub account (this just makes it easier on me)
 
+
+We use the traditional <a href="https://guides.github.com/introduction/flow/" target="_blank">Github Flow</a> to develop. This means that you fork the repo and checkout a branch to make changes, you submit a pull request (PR) to the development branch with your changes, and the development branch gets merged with master for official releases.
+
+
 ### Step 1. Fork the repo
 To contribute to the web based documentation, you should obtain a GitHub account and fork the <a href="{{site.repo}}" target="_blank">Singularity</a> repository. Once forked, you will want to clone the fork of the repo to your computer. Let's say my Github username is vsoch, and I am using ssh:
 
@@ -23,9 +27,10 @@ cd singularity/
 ```
 
 ### Step 2. Set up your config
-The github config file, located at .git/config, is the best way to keep track of many different forks of a repository. I usually open it up right after cloning my fork to add the repository that I forked as a <a href="https://help.github.com/articles/adding-a-remote/" target="_blank">remote</a>, so I can easily get updated from it. Let's say my .git/config first looks like this, after I clone my own branch:
+The github config file, located at `.git/config`, is the best way to keep track of many different forks of a repository. I usually open it up right after cloning my fork to add the repository that I forked as a <a href="https://help.github.com/articles/adding-a-remote/" target="_blank">remote</a>, so I can easily get updated from it. Let's say my .git/config first looks like this, after I clone my own branch:
 
 
+```bash
       [core]
               repositoryformatversion = 0
               filemode = true
@@ -37,9 +42,13 @@ The github config file, located at .git/config, is the best way to keep track of
       [branch "master"]
               remote = origin
               merge = refs/heads/master
+```
+
 
 I would want to add the upstream repository, which is where I forked from.
 
+
+```bash
       [core]
               repositoryformatversion = 0
               filemode = true
@@ -54,9 +63,13 @@ I would want to add the upstream repository, which is where I forked from.
       [branch "master"]
               remote = origin
               merge = refs/heads/master
+```
+
 
 I can also add some of my colleagues, if I want to pull from their branches:
 
+
+```bash
       [core]
               repositoryformatversion = 0
               filemode = true
@@ -75,20 +88,34 @@ I can also add some of my colleagues, if I want to pull from their branches:
               remote = origin
               merge = refs/heads/master
 
+```
+
+In the Github flow, the master branch is the frozen, current version of the software. Your master branch is always in sync with the upstream (our singularityware master), and the singularityware master is always the latest release of 
+
 This would mean that I can update my master branch as follows:
 
 ```bash
 git checkout master
 git pull upstream master
 git push origin master
 ```
+and then I would return to working on the branch for my feature. How to do that exactly? Read on!
+
+
 
 ### Step 3. Checkout a new branch
-<a href="https://guides.github.com/introduction/flow/" target="_blank">Branches</a> are a way of isolating your features. For example, if I am working on several features, I would want to keep them separate, and "submit them" (in what is called a <a href="https://help.github.com/articles/about-pull-requests/" target="_blank">pull request</a>) to be added to the main repository codebase. Each repository, including your fork, has a main branch, which is usually called "master". THe master branch of a fork should always be in sync with the repository it is forked from (which I usually refer to as "upstream") and then branches of the fork consistently updated with that master. Given that we've just cloned the repo, we know that we are in sync with master, and can immediately checkout a new branch
+<a href="https://guides.github.com/introduction/flow/" target="_blank">Branches</a> are a way of isolating your features. For example, if I am working on several features, I would want to keep them separate, and "submit them" (in what is called a <a href="https://help.github.com/articles/about-pull-requests/" target="_blank">pull request</a>) to be added to the main repository codebase. Each repository, including your fork, has a main branch, which is usually called "master". As mentioned earlier, the master branch of a fork should always be in sync with the repository it is forked from (which I usually refer to as "upstream") and then branches of the fork consistently updated with that master. Given that we've just cloned the repo, we probably want to work off of the current development branch, which has the most up to date "next version" of the software. So we can start by checking out that branch:
+
+```bash
+git checkout -b development
+git pull origin development
+```
+
+At this point, you can either choose to work on this branch, push to your origin development and pull request to singularityware development, or you can checkout another branch specific to your feature. We recommend always working from, and staying in sync with development. The command below would checkout a branch called `add/my-awesome-new-feature` from development.
 
 ```bash
 # Checkout a new branch called add/my-awesome-feature
-git checkout -b add/my-awesome-feature
+git checkout -b add/my-awesome-feature development
 ```
 
 The addition of the `-b` argument tells git that we want to make a new branch. If I want to just change branches (for example back to master) I can do the same command without `-b`:
@@ -100,6 +127,7 @@ git checkout master
 
 Note that you should commit changes to the branch you are working on before changing branches, otherwise they would be lost. Github will give you a warning and prevent you from changing branches if this is the case, so don't worry too much about it.
 
+
 ### Step 4. Make your changes
 On your new branch, go nuts! Make changes, test them, and when you are happy with a bit of progress, commit the changes to the branch:
 
@@ -134,7 +162,8 @@ git status
 
 ### Step 6. Submit a Pull Request
 
-Once you have pushed your branch, then you can go to either fork and (in the GUI) <a href="https://help.github.com/articles/creating-a-pull-request/" target="_blank">submit a Pull Request</a>. This will open up a nice conversation interface / forum for the developers of Singularity to discuss your contribution, likely after testing. At this time, any continuous integration that is linked with the code base will also be run. If there is an issue, you can continue to push commits to your branch and it will update the Pull Request.
+Once you have pushed your branch, then you can go to either fork and (in the GUI) <a href="https://help.github.com/articles/creating-a-pull-request/" target="_blank">submit a Pull Request</a>. Regardless of the name of your branch, your PR should be submit to the singularityware development branch. This will open up a nice conversation interface / forum for the developers of Singularity to discuss your contribution, likely after testing. At this time, any continuous integration that is linked with the code base will also be run. If there is an issue, you can continue to push commits to your branch and it will update the Pull Request.
+
 
 ## Support, helping and spreading the word!
 This is a huge endavor, and it is greatly appreciated! If you have been using Singularity and having good luck with it, join our <a href="https://groups.google.com/a/lbl.gov/forum/#!forum/singularity" target="_blank">Google Group</a> and help out other users! Post to online communities about Singularity, and request that your distribution vendor, service provider, and system administrators include Singularity for you!