AUTHORS

@@ -6,5 +6,5 @@
 ################################################################################
 ################################################################################
 
-Peter Toth <peter.toth198@gmail.com> (Original Author)
+Peter Toth <peter.toth198@gmail.com>
 Brandon Schneider <brandonschneider89@gmail.com>

CONTRIBUTING.md

@@ -0,0 +1,106 @@
+# Contribution guidelines
+
+Following the contribution guidelines saves everyone time, requires less back
+and forth during the review process, and helps to ensures a consistent codebase.
+*Note: historical code doesn't follow all of these guidelines*
+
+####A few general rules first:
+- Open any pull request against the `develop` branch
+- Use double quotes for everything that isn't a `FOR` loop.
+- Keep code to 80 characters or less, otherwise split them with a `\`. Only indent 4 spaces the first time you split the line:
+```
+long command \
+    next line \
+    next line \
+```
+- Comment your code
+- Do not use tabs, use spaces instead. 4 spaces to start, and 4 more for each additional nesting that occurs:
+```
+if [ "$(command | test)" ] ; then
+    if [ "$(new command | different test)" ] ; then
+        for _var in ${_var_list} ; do
+            stuff
+        done
+
+        if [ "$(last command | last test)" ] ; then
+            echo "Note same indentation as the previous for loop as this is " \
+                "not another nested level"
+        fi
+    fi
+fi
+```
+- Update ioc-help (**_not iocage.8/iocage.8.txt_**) if new/changed docs are needed for your change. Requires `txt2man`.
+<p>(`iocage help | txt2man -t iocage -s 8 -v "FreeBSD System Manager's Manual" > iocage.8`, followed by `iocage help > iocage.8.txt`)</p>
+- Pull request description should clearly show what the change is including output if relevant.
+- Squash commits before opening a pull request.
+- Test and then test again! Make sure it works with the latest changes in `develop`.
+- Use a line break between any statements/loops.
+<br>
+
+####IF statements
+-----
+- Use `-a` for AND operators and `-o` for OR operators.
+Use brackets and ensure that they follow this style:
+```
+if [ "${VAR}" = "string" ] ; then
+    stuff
+fi
+```
+<br>
+
+####FOR loops
+-----
+Make sure they follow this style:
+```
+for _var in ${_var_list} ; do
+    stuff
+done
+```
+
+<br>
+
+####WHILE loops
+-----
+Make sure they follow this style:
+```
+while [ "${?}" -gt 0 ] ; do
+    stuff
+done
+```
+
+<br>
+
+####CASE statements
+----
+Make sure they follow this style:
+```
+case "${_var}" in
+    string) stuff
+        ;;
+    another) more stuff
+        ;;
+esac
+```
+
+<br>
+
+####Variables and functions
+-----
+- Format functions as `__function_name ()`
+- Format local variables as `_var` and global variables as `var`
+- Use local variables for each function, avoid using global ones.
+- Use braces on all variables "${_var}"
+- Make sure you declare all variables at the top: `local _var1 _var2`
+- Use a line break between declaration and actual assignment:
+```
+local _var1 _var2
+
+_var1="foo"
+_var2="bar"
+```
+
+<br>
+
+####Documentation for Read The Docs
+-----
+If you wish to update some of our [documentation] (http://iocage.readthedocs.org), you only need to submit a PR for the files you change in iocage/doc/source. They will automatically be updated when the changes are merged into our `Master` branch.

ISSUE_TEMPLATE.md

@@ -0,0 +1,7 @@
+Make sure to follow and check these boxes before submitting an issue! Thank you.
+
+- [ ] Supply `iocage version`
+- [ ] Supply the commands used, along with any steps to recreate it.
+- [ ] Provide the output from `iocage`
+- [ ] Supply what you expected the result or output to be
+- [ ] Checked that the problem has not already been fixed on `develop` if using the stable release or `master` branch.

PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,6 @@
+Make sure to follow and check these boxes before submitting a PR! Thank you.
+
+- [ ] Supply documentation according to [CONTRIBUTING.md](https://github.com/iocage/iocage/blob/master/CONTRIBUTING.md)
+- [ ] Explain the feature
+- [ ] Read [CONTRIBUTING.md](https://github.com/iocage/iocage/blob/master/CONTRIBUTING.md)
+- [ ] Only open the PR against the `develop` branch.

README.md

@@ -1,3 +1,7 @@
+<h1>**No longer supported. iocage is being rewritten in a different language. To fetch 10.3-RELEASE or above, supply the release to iocage:
+<h2>`iocage fetch release=10.3-RELEASE`
+<h1>This will skip the interactive dialog and proceed.
+
 iocage
 ======
 
@@ -10,11 +14,34 @@ It is geared for ease of use with a simple and easy to understand command syntax
 iocage is in the FreeBSD ports tree as sysutils/iocage.
 To install using binary packages, simply run: `pkg install iocage`
 
+## WARNING:
+The `develop` branch may not be functional at any given point. This is where a lot of experimental work gets done. No guarantees for stability or migrations within the branch are given. Things can and do change rapidly. **_Please don't use it if you require stability._**
+
 - **[DOCUMENTATION](http://iocage.readthedocs.org/en/latest/index.html)**
-- **IRC**: [Freenode #iocage](https://www.irccloud.com/invite?hostname=irc.freenode.net&channel=%23iocage)
-- **Mailing list**: iocage@googlegroups.com
+- **Mailing list**: https://groups.google.com/forum/#!forum/iocage
 - **Contributing**: If you would like to submit a pull request, we kindly ask you to open it against the `develop` branch.
 
+####Raising an issue:
+
+We _like_ issues! If you are having trouble with `iocage` please open a GitHub [issue](https://github.com/iocage/iocage/issues) and we will ~~run around with our hair on fire~~ look into it. Before doing so, please give us some information about the situation:
+- Tell us what version of FreeBSD you are using with something like `uname -ro`
+- It would also be helpful if you gave us the output of `iocage version`
+- Most importantly, try to be detailed. Simply stating "I tried consoling into a jail and it broke" will not help us very much. However, saying something like this helps much, much more:
+
+
+"I tried to console into a _template_ jail, but it failed with _this error_ in which _I pasted below:_"
+````
+gasgiant ~ # iocage list -t
+JID  UUID                                  BOOT  STATE  TAG     TYPE
+-    XXXXXXXX-XXXX-XXXX-a5be-3417ebb13845  off   down   pepperd  template
+gasgiant ~ # iocage console salted
+cannot open 'zroot/iocage/jails/XXXXXXXX-XXXX-XXXX-a5be-3417ebb13845': dataset does not exist
+cannot open 'zroot/iocage/jails/XXXXXXXX-XXXX-XXXX-a5be-3417ebb13845': dataset does not exist
+[: -ne: unexpected operator
+  ERROR: jail: pepperd is not running!
+````
+- Use the [Markdown Basics](https://help.github.com/articles/markdown-basics/#code-formatting) GitHub page for more information on how to paste lines of code and terminal output. 
+
 **FEATURES:**
 - Templates, clones, basejails, fully independent jails
 - Ease of use
@@ -47,44 +74,51 @@ Start the jail:
 `iocage start myjail`
 
 **USAGE:**
--  iocage activate ZPOOL
--  iocage fetch [release=RELEASE | ftphost=ftp.hostname.org | ftpdir=/dir/ | ftpfiles="base.txz doc.txz lib32.txz src.txz"]
--  iocage create [-b|-c|-e] [release=RELEASE] [pkglist=file] [property=value]
--  iocage clone UUID|TAG@snapshot [property=value]
--  iocage destroy [-f] UUID|TAG|ALL
--  iocage reset UUID|TAG|ALL
--  iocage list [-t|-r]
--  iocage start UUID|TAG
--  iocage stop UUID|TAG
--  iocage restart UUID|TAG
--  iocage rcboot
--  iocage rcshutdown
--  iocage console UUID|TAG
--  iocage exec [-u username | -U username] UUID|TAG command [arg ...]
--  iocage chroot UUID|TAG [command]
--  iocage df
--  iocage show property
--  iocage get property|all UUID|TAG
--  iocage set property=value UUID|TAG
--  iocage cap UUID|TAG
--  iocage limits UUID|TAG
--  iocage uncap UUID|TAG
--  iocage inuse [UUID|TAG]
--  iocage snapshot UUID|TAG@snapshotname
--  iocage snaplist UUID|TAG
--  iocage snapremove UUID|TAG@snapshotname|ALL
--  iocage rollback UUID|TAG@snapshotname
--  iocage promote UUID|TAG
--  iocage runtime UUID|TAG
--  iocage update UUID|TAG
--  iocage upgrade UUID|TAG
--  iocage record start|stop UUID|TAG
--  iocage package UUID|TAG
--  iocage export UUID|TAG
--  iocage import UUID [property=value]
--  iocage defaults
--  iocage version | --version
--  iocage help
+```
+  iocage activate ZPOOL
+  iocage cap UUID|TAG
+  iocage chroot UUID|TAG [command]
+  iocage clean [-a|-r|-j]
+  iocage clone UUID|TAG [UUID|TAG@snapshot] [property=value]
+  iocage console UUID|TAG
+  iocage create [-b|-c|-e] [release=RELEASE] [pkglist=file] [property=value]
+  iocage deactivate ZPOOL
+  iocage defaults
+  iocage destroy [-f] UUID|TAG
+  iocage df
+  iocage exec [-u username | -U username] UUID|TAG|ALL command [arg ...]
+  iocage export UUID|TAG
+  iocage fetch [release=RELEASE | ftphost=ftp.hostname.org | ftpdir=/dir/ |
+                ftpfiles="base.txz doc.txz lib32.txz src.txz"]
+  iocage get property|all UUID|TAG
+  iocage help
+  iocage import UUID [property=value]
+  iocage init-host IP ZPOOL
+  iocage inuse UUID|TAG
+  iocage limits [UUID|TAG]
+  iocage list [-b|-t|-r]
+  iocage package UUID|TAG
+  iocage promote UUID|TAG
+  iocage rcboot
+  iocage reboot UUID|TAG
+  iocage rcshutdown
+  iocage record start|stop UUID|TAG
+  iocage reset UUID|TAG|ALL
+  iocage restart UUID|TAG
+  iocage rollback UUID|TAG@snapshotname
+  iocage runtime UUID|TAG
+  iocage set property=value UUID|TAG
+  iocage show property
+  iocage snaplist UUID|TAG
+  iocage snapremove UUID|TAG@snapshotname|ALL
+  iocage snapshot UUID|TAG [UUID|TAG@snapshotname]
+  iocage start UUID|TAG
+  iocage stop UUID|TAG
+  iocage uncap UUID|TAG
+  iocage update UUID|TAG
+  iocage upgrade UUID|TAG [release=RELEASE]
+  iocage version | --version
+  ```
 
 **REQUIREMENTS**
 - FreeBSD 9.3-RELEASE amd64 or newer

doc/source/advanced-use.rst

@@ -28,14 +28,14 @@ Promoting a clone
 
 **To promote a cloned jail, simply run:**
 
-``iocage promote UUID | TAG``
+``iocage promote UUID|TAG``
 
 The above step will reverse the clone and source jail relationship.
 Basically the clone will become the source and the source jail will be demoted to a clone.
 
 **Now you can remove the demoted jail with:**
 
-``iocage destroy UUID | TAG``
+``iocage destroy UUID|TAG``
 
 Updating jails
 --------------
@@ -45,7 +45,7 @@ while they are stopped or running.
 
 To update a jail to latest patch level run:
 
-``iocage update UUID | TAG``
+``iocage update UUID|TAG``
 
 This will create a back-out snapshot of the jail automatically.
 
@@ -79,7 +79,7 @@ Upgrade non-basejail
 
 To upgrade a normal jail (non basejail) to the hosts RELEASE run:
 
-``iocage upgrade UUID | TAG``
+``iocage upgrade UUID|TAG``
 
 This will upgrade the jail to the same RELEASE as the host.
 
@@ -187,14 +187,14 @@ Apply limits
 
 Apply limit on-the-fly:
 
-``iocage cap UUID | TAG``
+``iocage cap UUID|TAG``
 
 Check limits
 ++++++++++++
 
 Check active limits:
 
-``iocage limits UUID | TAG``
+``iocage limits UUID|TAG``
 
 Limit CPU use by %
 ++++++++++++++++++
@@ -206,7 +206,7 @@ Limit CPU execution to 20%:
 
 Check limits:
 
-``iocage limits UUID | TAG``
+``iocage limits UUID|TAG``
 
 Resetting a jail's properties
 +++++++++++++++++++++++++++++
@@ -215,7 +215,7 @@ If you have many properties on a jail that you would like to reset back to defau
 
 To reset to defaults:
 
-``iocage reset UUID | TAG``
+``iocage reset UUID|TAG``
 
 You can also reset every jail to the default properties:
 
@@ -249,3 +249,30 @@ Now simply create a jail and supply the pkgs.txt file:
 ``iocage create pkglist=/path-to/pkgs.txt tag=myjail``
 
 This will install ``nginx`` and ``tmux`` in the newly created jail.
+
+Using volumes
+-------------
+
+Jails can have shared directories from the host which is implemented using nullfs(5). The idea is based on volumes used in the docker world. Files can also be Volumes and are copied over at jail startup.
+
+The ``volumes`` property has the following syntax:
+    ::
+
+        /source/path(:/destination/path(:mount_options)) /another/source/path...
+
+``source_path`` is the minimum required input and causes ``destination_path`` to be the same as ``source_path``, but located within the jail's root path.
+
+All options are separated by a colon and multiple volumes can be specified by whitespace separation.
+All paths must be absolute and therefore start with a slash.
+Optionally comma separated ``mount_options`` can be passed onto the underlying mount command, mostly useful to specify read-only volumes. For files this is done by setting the immutable attribute after copying them into the jail.
+Volumes are only mounted during runtime.
+
+Volumes can be added at creation time:
+
+``iocage create volumes="/path/to/some/host/dir:/destination/within/jail/root /other/host/dir:/dest/in/jail:ro" tag=myjail``
+
+or set as a property later:
+
+``iocage set volumes="/new/path:/same/dir:ro" UUID|TAG``
+
+however the ``volumes`` property cannot be changed while the jail is running.

doc/source/basic-use.rst

@@ -143,7 +143,7 @@ Example, to turn off VNET capability for all newly created jails run:
 
 ``iocage set vnet=off default``
 
-Destroy a jails
+Destroy a jail
 ---------------
 
 To destroy a jail, simply run: