Contribution Guidelines

Cromwell is an open-source project and we heartily welcome community contributions to both our code and our documentation. Here are some guidelines for adding documentation and recommendations on where we could use help the most.

First off, here are useful links:

• Cromwell documentation: cromwell.readthedocs.io
• Source on Github: github.com/broadinstitute/cromwell
• Builds on ReadTheDocs: readthedocs.org/projects/cromwell
• How to build and view the documentation locally: mkdocs.readthedocs.io
• Public Google Docs - Table of Contents: drive.google.com/open?id=1myTVzWx5HG720nPBUAF9vE8XTacrzCW70RpgsjMnchM

"needs docs"

There are plenty of areas of the Cromwell documentation that need to be updated, improved, or added. Within the Cromwell repo on Github there are many issues labeled as "needs docs", so feel free to start there.

If you would like to request additional documentation, you can create a Github issue in the Cromwell repo.

Writing Tips

1. Keep it clear, accurate, and concise.
2. Put the most important information first.
3. Use the second person, use “you” instead of “the user”.
4. No passive verbs (everything is done by something).
5. Link to the original source, don't repeat documentation.

Formatting

The documentation is written in Markdown. Click here for a Github Guide on Markdown, and click here for more tips from MkDocs.

Styling

Links:

• Absolute: [link text](www.destinationURL.com) Example: [Broad Institute](www.broadinstitute.org) produces this link Broad Institute.
• Relative: [link text](Destination_Page), where Destination_Page is the file name without the .md extension
  Example: [How to use the Cromwell CLI](CommandLine) produces this link How to use the Cromwell CLI.
• Anchor link: [anchor text](../Path/To/Page#Anchor)
  Example: [HPC filesystems](backends/HPC#filesystems) produces this link HPC filesystems.

Code:

• To style a word of code, use a backtick (`) before and after the word.
  Example: `file.json` produces file.json.
• To style a block of code, use three backticks (```) before and after the block of code.
  Example:
  ```
  workflow myWorkflow {
  call myTask
  }
  ```
  produces this block

    workflow myWorkflow {  
    call myTask  
    }  

• To use syntax highlighting, include the language after the first three backticks (```).
  Example:
  ```json
  {
  "MyWorkflow.MyTask.VariableTwo": "Variable2"
  }
  ```
  produces this block

    {
        "MyWorkflow.MyTask.VariableTwo": "Variable2"
    }

Images

• Relative: ![](ImgName.png)
  • Example: ![](../jamie_the_cromwell_pig.png) produces this image
    
• Absolute: ![](URLofImg.png)
  • Example: ![](https://www.broadinstitute.org/sites/all/themes/custom/at_broad/logo.png) produces this image
    

REST API & Menu

REST API:

1. Edit the cromwell.yaml to make any changes to the REST API content.
2. Regenerate the REST API markdown file by running sbt generateRestApiDocs from the main Cromwell directory.
3. Commit both the changes to the cromwell.yaml and the (re)generated RESTAPI.md.
4. Once your branch is merged to the develop branch, you will see your changes on the REST API page.

Left-side menu:

To add or remove items from the menu, edit mkdocs.yml in Cromwell.

FAQs

Why isn't my documentation showing up?

• Is your PR merged?
  If not, kindly ask the team to merge it. Once your PR is merged to develop, it will trigger an automatic build.

• Has the build finished?
  Check build status here.

• Did you add the file(s) to the YAML file?
  If not, add it here.

How do I add to the REST API documentation?

• Don't forget to regenerate
  After you edit the cromwell.yaml, run sbt generateRestApiDocs and commit all changes.
  Hint: Once you have regenerated the docs correctly, the hidden timestamp at the top of the RESTAPI.md file will show the current time.