DC/OS Documentation

Documentation for the Datacenter Operating System (DC/OS)

These documents are used as source to generate dev.dcos.io/docs (staging) and dcos.io/docs (production). They are submoduled into dcos-website for deployment.

Issue tracking is moving to the DCOS JIRA (docs component). Issues on Github will be disabled soon.

Contributing

If this is your first contribution to an open source software (OSS) project, congratulations! Contributing to the documentation is a great way to get started. By following these instructions you can learn more about DC/OS, and contribute back to an OSS project right away. No expertise necessary!

This page provides instructions on how to contribute to the DC/OS documentation. The process ensures that work is not duplicated, and that your contributions are merged and approved by the admins. To get started you need a GitHub account and an account on the DC/OS JIRA.

• Making your contribution
• Styling and formatting your contribution
• Building and testing your content locally

Making your contribution

1. Search JIRA to review the currently open issues and make sure that no one is already working on your issue. If you find an open issue that is unassigned that you want to work, you can assign it to yourself! If you don’t see an issue related to yours, create a new issue, select documentation as the component, and assign it to yourself.

1. If this is your first contribution Fork the dcos-docs repo. (Once you’ve forked the repo, that fork stays associated with your GitHub account. If you try to fork it again GitHub will remind you that you already have a fork.)

2. Create a local repository, or if you already have one make sure it is up to date.

• If this is your first contribution, go to your terminal, navigate to the directory where you keep your Git projects, and clone your fork of the dcos-docs repo.

  $ git clone https://github.com/<your-user-name>/dcos-docs

• If this isn't your first contribution check out the master branch

  ```bash
  $ git checkout master
  ```
  

  and update it by following these instructions.

1. Create a new branch of your local repository using your JIRA number as the name. This way other contributors can find the JIRA issue that descirbes the goal of your contribution.

   $ git checkout -b dcos-nnn

2. Create your content.

• In most cases you should be able to create your content within the existing directory structure.
• If you're not sure how to add formatting, take a look at dcos.io/docs for examples.
• Be sure you follow the style and formatting guidelines in the next section.
• Don't forget to update your post's metadata if necessary, including the required metadata post_title and optional nav_title and menu_order. Where applicable, add the optional feature_maturity label. Description of various feature maturity phases can be found here.

The metadata should be at the very top of the post's file, and look something like this:

```
---
post_title: This is how you update the documentation
nav_title: Update Docs
menu_order: 5
feature_maturity: preview
---
The rest of your document's text will go here, underneath the second set of dashes.
```    

• Don't forget to save your changes

1. When you're happy with your improvements, build a local copy of the website by following these instructions to make sure that everything looks good, and that nothing is broken.

2. Push your changes into the feature branch of your remote repository on github.com.

3. First, add your changes (this gets them ready to be included in your commit).

```bash
$ git add .
```

1. Next commit the changes you made to your local branch, and add a useful message so that everyone knows what you've changed.

```bash
$ git commit -m "Addresses issue DCOS-nnn. More useful stuff here"
```

1. Finally push your changes up to your remote branch on GitHub, so that you can open a pull request.

```bash
$ git push origin dcos-nnn
```

1. Submit a pull request against the dcos-docs repo.

• Don't forget to add a link to this PR in your JIRA issue.
• Community managers will test drive and validate contributions that include hands-on instructions, and they'll probably ask for improvements or modifications by commenting on your PR. If you agree with their changes make them in your local repo and repeat steps 5-7 above, or feel free to continue the discussion.

Styling and formatting your contribution

• Use GitHub-flavored markdown.
• Use relative links.
  • Begin all links at the root docs level and include the version number subdirectory. (e.g., /docs/1.8/administration/sshcluster/).
• Do not include file extensions in your link or image paths. For example, the directory /docs/1.8/administration/ contains a file named user-management.md. To link to this content on the live site, you would use the following path: /docs/1.8/administration/user-management/.
• Each directory must contain an index.md file. This acts as the base-level topic for each folder in the site (required).
• The table of contents of each page is automatically generated based on the top-level headers.
  • Directory tables of contents are automatically generated based on post_title (or nav_title) and post_excerpt headers.
• Use active voice whenever possible.
• Use sentence-style capitalization for headings.

In addition to the above technical notes, make sure you read your doc for clarity and accuracy. Pretend you are someone else seeing your instructions for the first time, and try to follow them based only on the information you provided.

Building and testing your content locally

Pick one of the below methods to build your changes, integrated with the rest of dcos.io, on your local machine. This makes sure that your changes don't break the docs or the website. If you're not sure which method you should use to build the website locally, we recommend the automated build, because it has fewer prerequisites and is more reliable. If you find problems with your doc, edit the file. Your local build should update every time you save your changes.

Automated build

This method builds and launches a Docker container. For more information, see this PR.

Prerequisite

Latest version of Docker installed and running.

Building

1. Run sudo make.

   Tip: This can take up to 15 minutes to complete.

2. Visit localhost

Troubleshooting

If your build fails with an error (e.g. npm ERR! /website/npm-debug.log), try deleting the /dcos-docs/tmp directory and re-running the make command.

Manual build

We've implemented the dcos-docs repo as a submodule of the dcos-website repo. Fork the parent dcos-website repo and build the site locally. This will allow you to confirm that your content renders correctly and that all of your links work. For each step, follow the instructions for your operating system.

Prerequisites

1. Ruby

• CentOS

  $ sudo yum install -y ruby

• MacOS using Homebrew

  $ brew install ruby

1. Git

• CentOS

  $ sudo yum install git

• MacOS using Homebrew

  $ brew install git

1. Install EPEL repo, Node, and NPM.

• CentOS

  $ sudo yum install -y epel-release && sudo yum install -y nodejs && sudo yum install -y npm && npm update

• MacOS using Homebrew

  $ brew install -y nodejs
  $ brew install npm
  $ npm update

1. nvm 6.3.1

• CentOS

  $ curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.31.4/install.sh | bash
  $ nvm install 6.3.1 && nvm alias default 6.3.1

• MacOS

  $ curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.31.4/install.sh | bash
  $ nvm install 6.3.1 && nvm alias default 6.3.1

1. Gulp

• CentOS

  $ sudo npm install --global gulp-cli

• MacOS

  $ npm install --global gulp-cli

1. Clone the dcos-website repo.

$ git clone https://github.com/dcos/dcos-website

1. Check out the develop branch of dcos-website.

$ git checkout develop

1. Initialize the dcos-docs submodule with the content from the upstream master.

$ git submodule update --init --recursive

Optional: replace the content from the upstream master with the content from your local dcos-docs repo. Delete the dcos-website/dcos-dcos directory and replace it with a symlink to your local dcos-docs repo. For example, if your directory structure is /projects/dcos-website and /projects/dcos-docs, you can issue these commands from the dcos-website directory:

$ rm -r dcos-docs
$ ln -s <local-path-to-dcos-docs> dcos-docs

Building

Launch the local web server to view your changes.

$ npm start

License and Authors

Copyright 2016 Mesosphere, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this repository except in compliance with the License.

The contents of this repository are solely licensed under the terms described in the LICENSE file included in this repository.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Authors are listed in AUTHORS.md file.