Merge pull request #27 from londoncalling/kitematic-contrib-guide

Adding articles for Kitematic Contributors Guide

docs/kitematic/create_pr.md

@@ -0,0 +1,67 @@
+<!--[metadata]>
++++
+title = "Create a pull request (PR)"
+description = "Explains how to create a pull request for change or new feature"
+keywords = ["Kitematic, open source, contribute, contributor, tour, development, contribute, pull request, review, workflow, beginner, squash,  commit"]
+[menu.main]
+parent= "smn_kitematic_contrib"
+weight=5
++++
+<![end-metadata]-->
+
+# Create a pull request (PR)
+Make sure you follow the <a href="http://docs.docker.com/opensource/workflow/create-pr/#rebase-your-branch"
+target="_blank"> rebase guidelines </a> before you make a pull request.
+Rebasing helps verify that your commit is clean, and allows for an easier and faster merge of your code.
+
+Once you've cleaned up your commits:
+
+1. Push your code to your repository under the same name as your local branch.
+
+        $ git push origin xxxx-branch:xxxx-branch
+
+      where _xxxx_ is the number of the issue your worked on.
+
+2. Open a web browser to your fork on GitHub.
+
+    You should see the latest activity from your branch.
+
+3. Click "Compare & pull request."
+
+    The system displays the pull request dialog.
+
+    ![Pull Request dialog](images/pr_compare.png)
+
+    The pull request compares your changes to the `master` branch on the
+    `kitematic/kitematic` repository.
+
+4. Edit the pull request description and add a reference to the issue you are fixing.
+
+    GitHub helps you out by searching for the issue as you type.
+
+    ![Fixes issue](images/pr_describe_issue.png)
+
+5. Scroll down and verify the PR contains the commits and changes you expect.
+
+    For example, is the file count correct? Are the changes in the files what
+    you expect?
+
+    ![Commits](images/pr_commits_expected.png)
+
+6. Press "Create pull request".
+
+    The system creates the request and opens it for you in the `kitematic/kitematic`
+    repository.
+
+    ![Pull request made](images/pr_pull_request_made.png)
+
+
+## Where to go next
+
+Congratulations! You've created your first pull request to Kitematic!
+
+The next step in this process is to participate your PR's review. To learn more, and try another development exercise, see [where to learn more](next_steps.md) .
+
+<!-- The next step in the process for this PR is learn how to <a href="http://docs.docker.com/project/review-pr/"
+target=_blank">participate in your PR's
+review </a>. -->

docs/kitematic/find_issue.md

@@ -0,0 +1,47 @@
+
+<!--[metadata]>
++++
+title = "Find an issue"
+description = "Explains how to find a Kitematic issue"
+keywords = ["Kitematic, open source, contribute, contributor, tour "]
+[menu.main]
+parent = "smn_kitematic_contrib"
+weight=2
++++
+<![end-metadata]-->
+
+# Find an issue on GitHub
+Currently, the Kitematic GUI shows the name of a selected container, but not the ID. The tour shows you how to improve the GUI by adding the container ID to the display items, and integrate the updates into the codebase.
+
+To find and claim an issue you want to work on:
+
+1. Go to the `kitematic/kitematic` <a href="https://github.com/kitematic/kitematic" target="_blank">repository</a>.
+
+2. Click the "Issues" link.
+
+    A list of the open issues appears.
+
+    ![Open issues](images/list_open_issues.png)
+
+3. From the "Labels" drop-down, select <strong class="gh-label beginner">exp/beginner</strong>.
+
+    The system filters to show only open <strong class="gh-label beginner">exp/beginner</strong> issues.
+
+4. Open an issue that interests you.
+
+    The comments on the issues describe the problem and can provide information for a potential solution.
+
+    For this exercise we will select the issue #xxxx Missing container id.
+
+5. When you find an open issue that both interests you and is unclaimed, add a
+`#dibs` comment. Make sure that no other user has chosen to work on the issue.
+
+    The project does not permit external contributors to assign issues to themselves. Read the comments to find if a user claimed the issue by leaving a `#dibs` comment on the issue.
+
+6. Make a note of the issue number; you will need it for later.
+
+## Where to go next
+
+Go to next section to learn [Set up your Kitematic development environment](set_up_dev.md).
+
+(For more about working with open source issues in Docker, see <a href="http://docs.docker.com/opensource/workflow/find-an-issue/" target="_blank">Find an issue</a> and <a href="https://github.com/docker/docker/blob/master/CONTRIBUTING.md" target="_blank"> Docker Contributing Guidelines</a>.)

docs/kitematic/get_started.md

@@ -0,0 +1,37 @@
+<!--[metadata]>
++++
+title = "Get started"
+description = "Overview of Kitematic development process"
+keywords = ["Kitematic, open source, contribute, contributor, tour, development"]
+[menu.main]
+parent= "smn_kitematic_contrib"
+weight=1
++++
+<![end-metadata]-->
+
+## Contribute to Kitematic
+
+Kitematic is an open source project that simplifies the Docker experience. It
+automates Docker installation and setup, and provides an interactive graphical
+user interface (GUI) for working with containers. You can use Kitematic to create, run, and manage Docker containers, and find public images on Docker Hub.
+
+![Kitematic GUI](images/gui-splash-hub.png)
+
+See the <a href="http://docs.docker.com/kitematic/userguide" target="_blank"> Kitematic user guide</a> to learn more about it from a user perspective.
+
+## We welcome your contributions!
+We'd like to see Kitematic evolve
+with community contributed add-ons, extensions, themes, plug-ins, and cool, new
+features.
+## Start the developer tour
+If you're new to working with Docker open source projects or new to
+the Kitematic codebase, this quick tour will help you get started. Follow along with these steps to set up your Kitematic development environment and practice working on an example issue.
+
+1. [Find a Kitematic issue on GitHub and fork](find_issue.md)
+2. [Set up your Kitematic development environment and clone the repository](set_up_dev.md)
+3. [Develop in Kitematic (work on an issue)](work_issue.md)
+4. [Review your branch and create a pull request (PR)](create_pr.md)
+5. [Where to learn more](next_steps.md)
+
+## Where to go next
+[Find an issue on GitHub](find_issue.md) to get started.

docs/kitematic/index.md

@@ -0,0 +1,19 @@
+<!--[metadata]>
++++
+title = "Contribute to Kitematic"
+description = "Introduces Kitematic contribute topics and tour"
+keywords = ["Kitematic, open source, contribute, contributor, tour, issue, review"]
+[menu.main]
+parent="mn_oss_contrib"
+identifier="smn_kitematic_contrib"
+weight=1
++++
+<![end-metadata]-->
+
+# Contribute to Kitematic
+* [Get started] (get_started.md)
+* [Find an issue on GitHub](find_issue.md)
+* [Set up for Kitematic development](set_up_dev.md)
+* [Develop in Kitematic (work on an issue)](work_issue.md)
+* [Review your branch and create a pull request (PR)] (create_pr.md)
+* [Where to learn more](next_steps.md)

docs/kitematic/next_steps.md

@@ -0,0 +1,44 @@
+<!--[metadata]>
++++
+title = "Where to learn more"
+description = "Explains next steps after the tour"
+keywords = ["Kitematic, open source, contribute, contributor, tour, development, contribute"]
+[menu.main]
+parent= "smn_kitematic_contrib"
+weight=6
++++
+<![end-metadata]-->
+
+# Where to learn more
+
+You've just created your first pull request to Kitematic!
+
+The next
+step is to learn how to <a href="http://docs.docker.com/opensource/workflow/review-pr/" target="_blank">participate in your PR's
+review</a>.
+
+## Take the development challenge
+
+Now that you’ve had some practice, try adding another feature to Kitematic on your own.
+
+As you learned in the previous exercise, adding the container id to the container Settings tab is fairly simple.
+
+Let's provide another missing piece of information for Kitematic users:
+
+_When I look at an active container in Kitematic, I want to know what command the container is currently running_
+
+![An active container in Kitematic](images/kitematic_gui_container_id.png)
+
+In a terminal window, users can get this by looking at running containers with: `docker ps`
+
+As an exercise, implement the code changes needed to display the current container's running command. When you are ready to share the new mini feature, create a PR for it.
+
+## Learn more about open source
+To learn more about contributing to Docker open source projects, see:
+
+* <a href="http://docs.docker.com/opensource/project/who-written-for/" target="_blank">
+ README First</a>
+
+* <a href="http://docs.docker.com/opensource/code/" target="_blank"> Quick Start contribution </a>
+
+* <a href="http://docs.docker.com/opensource/workflow/make-a-contribution/" target="_blank"> Understand how to contribute </a>

docs/kitematic/set_up_dev.md

@@ -0,0 +1,157 @@
+<!--[metadata]>
++++
+title = "Set up for Kitematic development"
+description = "Explains how to find a Kitematic issue"
+keywords = ["Kitematic, open source, contribute, contributor, tour, development"]
+[menu.main]
+parent= "smn_kitematic_contrib"
+weight=3
++++
+<![end-metadata]-->
+
+# Set up for Kitematic development
+
+Kitematic is built on top of:
+
+* <a href="http://electron.atom.io/" target="_blank"> Electron </a>
+
+* <a href="https://nodejs.org" target="_blank"> Node.js </a>
+
+* <a href="https://facebook.github.io/react/" target="_blank"> React </a> and <a href="https://facebook.github.io/react/" target="_blank"> AltJS </a> (which follows the Flux pattern)
+
+## Download and install NVM
+
+To get started, you will need to install Node.js v4.2.1. Using Node Version Manager (NVM) makes the Node.js install easy.
+
+### Windows:
+1. Download <a href="https://github.com/coreybutler/nvm-windows/releases/"
+target="_blank"> latest release </a>
+
+2. Follow the installer steps to get NVM installed. Please note, you need to
+uninstall any existing versions of node.js before installing NVM for Windows;
+the above installer link will have an uninstaller available.
+
+  ![windows installer](images/nvm_install.jpeg)
+
+### Mac OSX/Linux:
+
+1. Open a terminal window
+
+2. Copy and paste the following install script:
+
+        curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.29.0/install.sh | bash
+
+3. To activate nvm, close the terminal window and re-open a new one.
+
+    (Alternatively, you can source nvm from your current shell with the command `. ~/.nvm/nvm.sh` )
+
+(To learn more about working with NVM, see <a href="https://github.com/creationix/nvm" target="_blank">Mac OSX/Linux official nvm repo</a>, <a href="https://github.com/coreybutler/nvm-windows" target="_blank">Windows official nvm repo</a>, and <a href="https://www.digitalocean.com/community/tutorials/how-to-install-node-js-with-nvm-node-version-manager-on-a-vps" target="_blank">How To Install Node.js with NVM ON A VPS</a>)
+
+## Install Node.js
+
+1. Install the proper Node.js version.
+
+        $ nvm install v4.2.1
+
+2. Make this version the default.
+
+        $ nvm alias default v4.2.1
+
+3. Run `node --version` to confirm that you are now using the proper Node.js version.
+
+        $ node --version
+
+## Fork the master branch of Kitematic
+
+To fork the master branch of Kitematic:
+
+1. Go to the <a href="https://github.com/kitematic/kitematic "target="_blank">
+kitematic/kitematic repository </a>.
+
+2. Click "Fork" in the upper right corner of the GitHub interface.
+
+    GitHub forks the repository to your GitHub account. The original
+    `kitematic/kitematic` repository becomes a new fork `YOUR_ACCOUNT/kitematic`
+    under your account.
+
+3. Copy your fork's clone URL from GitHub.
+
+    GitHub allows you to use HTTPS or SSH protocols for clones. You can use the `git` command line or clients like Subversion to clone a repository. This guide assume you are using the HTTPS protocol and the `git` command line. If you are comfortable with SSH and some other tool, feel free to use that instead. You'll need to convert what you see in the guide to what is appropriate to your tool.
+
+## Clone your repository locally and create a branch
+
+To clone your repository and create a branch for the issue:
+
+1. Open a terminal window on your local host and change to your home directory.
+
+        $ cd ~
+
+    In Windows, you'll work in your Docker Quickstart Terminal window instead of Powershell or a `cmd` window.
+
+2. Create a directory for your new repository and change into that directory.
+
+3. From the root of your repository, clone the fork to your local host.
+
+        $ git clone https://github.com/YOUR_USERNAME/kitematic.git
+
+4. Create and checkout a branch for the issue you will be working on.
+
+        $ git checkout -b xxxx-branch
+
+    where _xxxx_ is the number of the issue previously noted.
+
+## Set up your signature and upstream remote
+You can set your signature globally or locally.
+
+1. Set your `user.name` for the repository.
+
+        $ git config --local user.name "FirstName LastName"
+
+2. Set your `user.email` for the repository.
+
+        $ git config --local user.email "emailname@mycompany.com"
+
+3. Check the result in your `git` configuration.
+
+        $ git config --local --list
+
+4. Set your local repository to track changes upstream, on the `kitematic`
+repository.
+
+        $ git remote add upstream https://github.com/kitematic/kitematic.git
+
+(To learn more, see <a
+href="http://docs.docker.com/opensource/project/set-up-git/#set-your-signature-and-an-upstream-remote" target="_blank"> Set up your signature and an upstream remote</a>.)
+
+## Install dependencies, start Kitematic, and verify your setup
+Your Node.js install includes npm for package management. You'll use it to install supporting packages and start the app.
+
+1. Verify that the package manager is running and check the version (at the time of this writing, v2.14.7).
+
+        $ npm --version
+
+2. Install the package dependencies.
+
+        $ npm install
+
+3. From the root of your kitematic repository, use the package manager to start Kitematic and confirm everything went well.
+
+        $ npm start
+
+All of the core files in Kitematic are in the `src` folder, which then
+follows the AltJS structure of:
+```
+kitematic/
+|--src/
+    |--actions/
+    |  |--MyActions.js
+    |--stores/
+    |  |--MyStore.js
+    |--components/
+    |  |--MyComponent.react.js
+```
+The `components` folder is where the layout files are, the `stores` represent the application logic and `actions` are the dispatcher for actions taken within the `components`.
+
+## Where to go next
+You are ready to start working on the issue. Go to [Develop in Kitematic (work
+on an issue)](work_issue.md).

docs/kitematic/work_issue.md

@@ -0,0 +1,79 @@
+<!--[metadata]>
++++
+title = "Develop in Kitematic (work on an issue)"
+description = "Explains how to find a Kitematic issue"
+keywords = ["Kitematic, open source, contribute, contributor, tour, development"]
+[menu.main]
+parent= "smn_kitematic_contrib"
+weight=4
++++
+<![end-metadata]-->
+
+## Develop in Kitematic (work on an issue)
+
+For this tutorial, we will work on issue #XXXX which is a request to display the container id in Kitematic for easy identification. (Currently, Kitematic shows the container name but not the id.)
+
+To do this, edit the container `General Settings` layout.
+
+1. Open the project in your favorite editor - We recommend using <a href="https://atom.io/" target="_blank"> Atom</a> as it's a full featured editor with great <a href="http://eslint.org/" target="_blank"> ES lint</a> support to keep your code organized.
+
+2. Open the `ContainerSettingsGeneral.react.js` file which is found under the `src/components/` folder and look for the following piece of code, which is in fact the layout (like HTML in the browser):
+
+    ```
+        return (
+		    <div className="settings-panel">
+		    ...
+    ```
+    (line ~200)
+
+3. Above this code we will create a javascript variable that will allow us to display  our container id:
+
+    ```
+    let shortId = (
+        <div className="settings-section">
+            <h3>Container Id</h3>
+            <div className="container-name">
+                <input id="input-container-name" type="text" className="line" placeholder="Container Id" defaultValue={this.props.container.Id.substr(0, 12)} readOnly></input>
+            </div>
+        </div>
+    );
+    ```
+
+    This snippet has been saved as a <a href="https://gist.github.com/FrenchBen/0f514e7b3c584e8d46b5" target="_blank">GitHub gist</a>.
+
+4. We then need to add the variable to the rendered view, by adding it below the `{rename}` tag. The new render code should look something like:
+
+     ```
+          return (
+               <div className="settings-panel">
+                    {rename}
+                    {shortId}
+    ```
+  At this point, the updated code should look similar to this:
+
+    ![Javascript to display container id in kitematic](images/settings-code-example.png)
+
+5. Save the code changes, re-start Kitematic.
+
+        $ npm start
+
+     Now, the container ID should show on the General Settings tab, along with the container name.
+
+     ![Container ID](images/kitematic_gui_container_id.png)
+
+     *Note that the container ID in Kitematic matches the ID shown as output to the `docker ps` command.*
+
+6. You can close the Kitematic application now, and kill the running process in the terminal via CTRL+c.
+
+7. Stage your changes by adding them.
+
+        $ git add src/components/ContainerSettingsGeneral.react.js
+
+8. Commit your code changes with a comment that explains what this fixes or closes.
+
+        $ git commit -s -m "added container ID to show on settings tab, fixes issue #1191"
+
+    (See <a href="https://github.com/docker/docker/blob/master/CONTRIBUTING.md#coding-style" target="_blank">Coding Style</a> in the general guidelines on <a href="https://github.com/docker/docker/blob/master/CONTRIBUTING.md" target="_blank">Contributing to Docker</a>.)
+
+## Where to go next
+At this point, you are ready to [Review your branch and create a pull request](create_pr.md) to merge your new feature into Kitematic.