Skip to content

Guidelines for updating GATK javadoc

Jump to bottom
Soo Hee Lee edited this page Mar 7, 2019 · 7 revisions

This document is here at the request of the GATK Communications Team and outlines the general steps involved when updating GATK tool documentation. External contributors may also wish to follow these guidelines.

  • To make changes to Picard tool javadoc, do so in the picard repository. A GATK release will reflect the changes in the latest release of Picard. The guidelines should still apply.
  • For javadoc to translate to gatkDoc and ultimately end up on the GATK forum, certain feature tags must be present. See the wiki article here for details on the Barclay system and its annotations.
  • For how to update the GATK Forum tool documentation for the latest gatk release, see instead the wiki article here.

If you are not currently a contributor and are requesting documentation updates

Please post requests to the GATK forum at https://gatkforums.broadinstitute.org/gatk/discussions. The GATK Frontline Support team will consider and process your request on your behalf.

If you are a developer yourself and feel strongly about the updates you want, you may submit a new issue ticket directly in the repo at https://github.com/broadinstitute/gatk/issues. Please note it may be a while before a developer sees or considers your request.

If you will directly make documentation updates to the codebase

Changes should start as an issue ticket discussion with one of the current developers and lead to a pull request (PR) in the respective codebase. An outline of the steps follow.

These steps presume rudimentary knowledge of git version control practices and a GitHub account. You can either make git-tracked updates (i) using the GitHub web UI or (ii) through the terminal verison of git. Consider use of tools such as intelliJ IDEA or SublimeText. For intelliJ, ask Broad BITs for the license key or consider taking advantage of the free thirty-minutes per session the software offers as of this writing.

  1. Discuss exactly the scope of changes, via gatk repo github issue ticket.
  2. Make GoogleDoc version of the document in question. Please do so in the DSDE>DSDE Internal>Comms Team Internal>GATK documentation folder and share access with those involved appropriately.
  3. Propose and track changes so they are clearly visible.
  4. Get feedback from an expert.
  5. Incorporate feedback to GoogleDoc version.
  6. To a git branch of the codebase, make changes to the code, either via the GitHub web UI or through IntelliJ as mentioned above.
  7. Commit changes and note changes in the commit message.
  8. Make a pull request, attach the issue ticket to the PR, and assign the developer to review. Ideally, the PR needs to be reviewed by someone from the GATK Methods Development team, in particular, if any changes are to outside of the javadoc portion.
  9. Once Travis checks pass and the reviewer gives the go-ahead, merge changes. The reviewer may request additional changes so expect to iterate over steps 3-9.
  10. Delete the branch. The master branch and the next release of GATK will reflect updates.

Here is an example set of issue ticket and PR illustrating the outlined process:

And here is an issue ticket with additional details in the context of GATK4.0.0.0 tool document updates.

ERRATA

  1. LaTeX rendering use e.g. <img src="http://latex.codecogs.com/svg.latex?$$ refRatio = \frac{min(X[0][0], X[0][1])}{max(X[0][0], X[0][1])} $$" border="0"/> as illustrated in https://github.com/broadinstitute/gatk/pull/5703. The equation starts and ends with $$.
Clone this wiki locally