istio.io/archive/v0.2/docs/reference/contribute/reviewing-doc-issues.html

2 lines
23 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html><html lang="en" itemscope itemtype="https://schema.org/WebPage" style="overflow-y: scroll;"><head><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="title" content="Doc Issues"><meta name="og:title" content="Doc Issues"><meta name="og:image" content="/v0.2/img/logo.png"/><meta name="description" content="Explains the process involved in accepting documentation updates."><meta name="og:description" content="Explains the process involved in accepting documentation updates."><title>Istioldie 0.2 / Doc Issues</title><script> window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date; ga('create', 'UA-98480406-2', 'auto'); ga('send', 'pageview'); </script> <script async src='https://www.google-analytics.com/analytics.js'></script><link rel="alternate" type="application/rss+xml" title="Istio Blog RSS" href="/v0.2/feed.xml"><link rel="apple-touch-icon" href="/v0.2/favicons/apple-touch-icon.png" sizes="180x180"><link rel="icon" type="image/png" href="/v0.2/favicons/android-chrome-96x96.png" sizes="96x96" ><link rel="icon" type="image/png" href="/v0.2/favicons/favicon-32x32.png" sizes="32x32"><link rel="icon" type="image/png" href="/v0.2/favicons/favicon-16x16.png" sizes="16x16"><link rel="manifest" href="/v0.2/favicons/manifest.json"><link rel="mask-icon" href="/v0.2/favicons/safari-pinned-tab.svg" color="#2DA6B0"><meta name="msapplication-TileColor" content="#ffffff"><meta name="msapplication-TileImage" content="/v0.2/favicons/mstile-150x150.png"><link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:400,100,100italic,300,300italic,400italic,500,500italic,700,700italic,900,900italic"><link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css"><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"><link rel="stylesheet" href="/v0.2/css/all.css"><link rel="stylesheet" href="/v0.2/css/prism.css"> <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.4/jquery.min.js"></script></head><body class="language-unknown"><div class="nav-hero-container" style="z-index: 200000;"><nav id="header-nav" class="navbar navbar-inverse" role="navigation"><div class="container"><div class="row"><div class="col-md-11 nofloat center-block "><div class="navbar-header"> <button type="button" class="hamburger navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar-collapse-1" aria-expanded="false"> <span class="sr-only">Toggle navigation</span> <span class="icon-bar"></span> <span class="icon-bar"></span> <span class="icon-bar"></span> </button> <a class="navbar-brand" href="/v0.2/"><div> <img src="/v0.2/img/logo.png" alt="Istio" width="36px" height="54px"/> <span class="brand-name">Istioldie 0.2</span></div></a></div><div class="collapse navbar-collapse" id="navbar-collapse-1"><ul class="nav navbar-nav navbar-right"><li><a href="/v0.2/about/" >About</a></li><li><a href="/v0.2/docs/" class='current'>Docs</a></li><li><a href="/v0.2/blog/" >Blog</a></li><li><a href="/v0.2/community/" >Community</a></li><li><a href="/v0.2/faq/" >FAQ</a></li><li class="dropdown"><li class="dropdown"> <a class="dropdown-toggle" data-toggle="dropdown" href=""> <i class='fa fa-lg fa-cog'></i> <span class="caret"></span> </a><ul class="dropdown-menu"><h6 class="dropdown-header">Other versions of this site</h6><li> <a href="https://istio.io">Current Release</a></li><li> <a href="https://preliminary.istio.io">Next Release</a></li><li> <a href="https://archive.istio.io">Older Releases</a></li></ul></li><li><form name="cse" id="searchbox_demo" class="navbar-form navbar-right" role="search"> <input type="hidden" name="cx" value="013699703217164175118:iwwf17ikgf4" /> <input type="hidden" name="ie" value="utf-8" /> <input type="hidden" name="hl" value="en" /><div class="form-group"><div class="input-group"> <input name="q" class="form-control" type="text" size="30" /><div class="input-group-addon"> <span class="btn-search glyphicon glyphicon-search"></span></div></div></div></form> <script type="text/javascript" src="https://www.google.com/cse/brand?form=searchbox_demo"></script></li></ul></div></div></div></div></nav></div><div class="container"><div class="row"><div class="col-md-11 nofloat center-block" style="margin-top: 3px;"><ul class="col-sm-10 nav nav-tabs"><li role="presentation" ><a href="/v0.2/docs/">Welcome</a></li><li role="presentation" ><a href="/v0.2/docs/concepts/">Concepts</a></li><li role="presentation" ><a href="/v0.2/docs/setup/">Setup</a></li><li role="presentation" ><a href="/v0.2/docs/tasks/">Tasks</a></li><li role="presentation" ><a href="/v0.2/docs/guides/">Guides</a></li><li role="presentation" class='active'><a href="/v0.2/docs/reference/">Reference</a></li></ul></div></div></div><script src="/v0.2/js/navtree.js"></script><div class="container docs"><div class="row"><div class="col-md-11 nofloat center-block"><div class="row"><div id="sidebar-container" class="col-sm-3"><ul class="doc-side-nav"><li><h5 class='doc-side-nav-title'>Reference</h5></li><script type="text/javascript"> var docs = []; docs.push({path: [ "api", "index.md", ], url: "/docs/reference/api/", title: "API", order: 10, overview: "Detailed information on API parameters."}); docs.push({path: [ "api", "mixer", "index.md", ], url: "/docs/reference/api/mixer/", title: "Mixer", order: 10, overview: "Detailed information on configuration and API exposed by Mixer."}); docs.push({path: [ "api", "mixer", "mixer-service.md", ], url: "/docs/reference/api/mixer/mixer-service.html", title: "Mixer Service", order: 20, overview: "Generated documentation for Mixer's API Surface"}); docs.push({path: [ "api", "mixer", "status.md", ], url: "/docs/reference/api/mixer/status.html", title: "Status RPC", order: 40, overview: "Google's rpc.Status proto"}); docs.push({path: [ "commands", "index.md", ], url: "/docs/reference/commands/", title: "CLI", order: 30, overview: "Describes usage and options of the Istio CLI and other utilities."}); docs.push({path: [ "commands", "istio_ca.md", ], url: "/docs/reference/commands/istio_ca.html", title: "istio_ca", order: 301, overview: "Istio Certificate Authority (CA)"}); docs.push({path: [ "commands", "istioctl.md", ], url: "/docs/reference/commands/istioctl.html", title: "istioctl", order: 20, overview: "Istio control interface"}); docs.push({path: [ "commands", "mixc.md", ], url: "/docs/reference/commands/mixc.html", title: "mixc", order: 101, overview: "Utility to trigger direct calls to Mixer's API."}); docs.push({path: [ "commands", "mixs.md", ], url: "/docs/reference/commands/mixs.html", title: "mixs", order: 201, overview: "Mixer is Istio's abstraction on top of infrastructure backends."}); docs.push({path: [ "config", "index.md", ], url: "/docs/reference/config/", title: "Configuration", order: 20, overview: "Detailed information on configuration options."}); docs.push({path: [ "config", "mixer", "adapters", "denier.md", ], url: "/docs/reference/config/mixer/adapters/denier.html", title: "denier Config", order: 100, overview: "Generated documentation for Mixer's denier Adapter Configuration Schema"}); docs.push({path: [ "config", "mixer", "adapters", "index.md", ], url: "/docs/reference/config/mixer/adapters/", title: "Adapters", order: 40, overview: "Generated documentation for Mixer's adapters."}); docs.push({path: [ "config", "mixer", "adapters", "kubernetes.md", ], url: "/docs/reference/config/mixer/adapters/kubernetes.html", title: "kubernetes Config", order: 10, overview: "Generated documentation for Mixer's kubernetes Adapter Configuration Schema"}); docs.push({path: [ "config", "mixer", "adapters", "list.md", ], url: "/docs/reference/config/mixer/adapters/list.html", title: "list Config", order: 20, overview: "Generated documentation for Mixer's list Adapter Configuration Schema"}); docs.push({path: [ "config", "mixer", "adapters", "memquota.md", ], url: "/docs/reference/config/mixer/adapters/memquota.html", title: "memquota Config", order: 30, overview: "Generated documentation for Mixer's memquota Adapter Configuration Schema"}); docs.push({path: [ "config", "mixer", "adapters", "prometheus.md", ], url: "/docs/reference/config/mixer/adapters/prometheus.html", title: "prometheus Config", order: 40, overview: "Generated documentation for Mixer's prometheus Adapter Configuration Schema"}); docs.push({path: [ "config", "mixer", "adapters", "stackdriver.md", ], url: "/docs/reference/config/mixer/adapters/stackdriver.html", title: "stackdriver Config", order: 50, overview: "Generated documentation for Mixer's stackdriver Adapter Configuration Schema"}); docs.push({path: [ "config", "mixer", "adapters", "statsd.md", ], url: "/docs/reference/config/mixer/adapters/statsd.html", title: "statsd Config", order: 60, overview: "Generated documentation for Mixer's statsd Adapter Configuration Schema"}); docs.push({path: [ "config", "mixer", "adapters", "stdio.md", ], url: "/docs/reference/config/mixer/adapters/stdio.html", title: "stdio Config", order: 70, overview: "Generated documentation for Mixer's stdio Adapter Configuration Schema"}); docs.push({path: [ "config", "mixer", "adapters", "svcctrl.md", ], url: "/docs/reference/config/mixer/adapters/svcctrl.html", title: "svcctrl Config", order: 80, overview: "Generated documentation for Mixer's svcctrl Adapter Configuration Schema"}); docs.push({path: [ "config", "mixer", "attribute-manifests.md", ], url: "/docs/reference/config/mixer/attribute-manifests.html", title: "Attribute Manifests", order: 15, overview: "Describes the resource containing the collection of attributes known to Mixer at runtime."}); docs.push({path: [ "config", "mixer", "attribute-vocabulary.md", ], url: "/docs/reference/config/mixer/attribute-vocabulary.html", title: "Attribute Vocabulary", order: 10, overview: "Describes the base attribute vocabulary used for policy and control."}); docs.push({path: [ "config", "mixer", "expression-language.md", ], url: "/docs/reference/config/mixer/expression-language.html", title: "Expression Language", order: 20, overview: "Mixer config expression language reference."}); docs.push({path: [ "config", "mixer", "index.md", ], url: "/docs/reference/config/mixer/", title: "Mixer", order: 30, overview: "Detailed information on configuration and API exposed by Mixer."}); docs.push({path: [ "config", "mixer", "policy-and-telemetry-rules.md", ], url: "/docs/reference/config/mixer/policy-and-telemetry-rules.html", title: "Policy and Telemetry Rules", order: 40, overview: "Describes the rules used to configure Mixer policy and telemetry."}); docs.push({path: [ "config", "mixer", "template", "checknothing.md", ], url: "/docs/reference/config/mixer/template/checknothing.html", title: "checknothing Config", order: 1150, overview: "Generated documentation for Mixer's Template Configuration Schema"}); docs.push({path: [ "config", "mixer", "template", "index.md", ], url: "/docs/reference/config/mixer/template/", title: "Templates", order: 50, overview: "Generated documentation for Mixer's Templates."}); docs.push({path: [ "config", "mixer", "template", "listentry.md", ], url: "/docs/reference/config/mixer/template/listentry.html", title: "listentry Config", order: 1160, overview: "Generated documentation for Mixer's Template Configuration Schema"}); docs.push({path: [ "config", "mixer", "template", "logentry.md", ], url: "/docs/reference/config/mixer/template/logentry.html", title: "logentry Config", order: 1170, overview: "Generated documentation for Mixer's Template Configuration Schema"}); docs.push({path: [ "config", "mixer", "template", "metric.md", ], url: "/docs/reference/config/mixer/template/metric.html", title: "metric Config", order: 1180, overview: "Generated documentation for Mixer's Template Configuration Schema"}); docs.push({path: [ "config", "mixer", "template", "quota.md", ], url: "/docs/reference/config/mixer/template/quota.html", title: "quota Config", order: 1190, overview: "Generated documentation for Mixer's Template Configuration Schema"}); docs.push({path: [ "config", "mixer", "template", "reportnothing.md", ], url: "/docs/reference/config/mixer/template/reportnothing.html", title: "reportnothing Config", order: 1200, overview: "Generated documentation for Mixer's Template Configuration Schema"}); docs.push({path: [ "config", "mixer", "value-type.md", ], url: "/docs/reference/config/mixer/value-type.html", title: "Value Type", order: 50, overview: "Generated documentation for Mixer Config's Value Type"}); docs.push({path: [ "config", "service-mesh.md", ], url: "/docs/reference/config/service-mesh.html", title: "Service Mesh", order: 15, overview: "Global Configuration Schema"}); docs.push({path: [ "config", "traffic-rules", "destination-policies.md", ], url: "/docs/reference/config/traffic-rules/destination-policies.html", title: "Destination Policies", order: 30, overview: "Client-side traffic management policies configuration schema"}); docs.push({path: [ "config", "traffic-rules", "egress-rules.md", ], url: "/docs/reference/config/traffic-rules/egress-rules.html", title: "Egress Rules", order: 40, overview: "Routing configuration for traffic exiting the service mesh"}); docs.push({path: [ "config", "traffic-rules", "index.md", ], url: "/docs/reference/config/traffic-rules/", title: "Traffic Management Rules", order: 20, overview: "Detailed information on rules configuration and API exposed by Pilot for managing them."}); docs.push({path: [ "config", "traffic-rules", "routing-rules.md", ], url: "/docs/reference/config/traffic-rules/routing-rules.html", title: "Routing Rules", order: 20, overview: "Traffic routing rule configuration schema"}); docs.push({path: [ "contribute", "creating-a-pull-request.md", ], url: "/docs/reference/contribute/creating-a-pull-request.html", title: "Creating a Pull Request", order: 20, overview: "Shows you how to create a GitHub pull request in order to submit your docs for approval."}); docs.push({path: [ "contribute", "editing.md", ], url: "/docs/reference/contribute/editing.html", title: "Editing Docs", order: 10, overview: "Lets you start editing this site's documentation."}); docs.push({path: [ "contribute", "index.md", ], url: "/docs/reference/contribute/", title: "Contributing to the Docs", order: 100, overview: "Learn how to contribute to improve and expand the Istio documentation."}); docs.push({path: [ "contribute", "reviewing-doc-issues.md", ], url: "/docs/reference/contribute/reviewing-doc-issues.html", title: "Doc Issues", order: 60, overview: "Explains the process involved in accepting documentation updates."}); docs.push({path: [ "contribute", "staging-your-changes.md", ], url: "/docs/reference/contribute/staging-your-changes.html", title: "Staging Your Changes", order: 40, overview: "Explains how to test your changes locally before submitting them."}); docs.push({path: [ "contribute", "style-guide.md", ], url: "/docs/reference/contribute/style-guide.html", title: "Style Guide", order: 70, overview: "Explains the dos and donts of writing Istio docs."}); docs.push({path: [ "contribute", "writing-a-new-topic.md", ], url: "/docs/reference/contribute/writing-a-new-topic.html", title: "Writing a New Topic", order: 30, overview: "Explains the mechanics of creating new documentation pages."}); docs.push({path: [ "glossary.md", ], url: "/docs/reference/glossary.html", title: "Glossary", order: 40, overview: "A glossary of common Istio terms."}); docs.push({path: [ "index.md", ], url: "/docs/reference/", title: "Reference", order: 60, overview: "The Reference section contains detailed authoritative reference material such as command-line options, configuration options, and API calling parameters."}); docs.push({path: [ "notes", "0.1.md", ], url: "/docs/reference/notes/0.1.html", title: "Istio 0.1", order: 50, overview: ""}); docs.push({path: [ "notes", "index.md", ], url: "/docs/reference/notes/", title: "Prior Release Notes", order: 600, overview: "Release notes for prior versions of Istio."}); docs.push({path: [ "release-notes.md", ], url: "/docs/reference/release-notes.html", title: "Release Notes", order: 50, overview: "What's been happening with Istio"}); docs.push({path: [ "release-roadmap.md", ], url: "/docs/reference/release-roadmap.html", title: "Roadmap", order: 60, overview: "What Istio will become in the coming months."}); docs.push({path: [ "writing-config.md", ], url: "/docs/reference/writing-config.html", title: "Writing Configuration", order: 70, overview: "How to write Istio config YAML content."}); genNavBarTree(docs) </script></ul></div><div id="tab-container" class="col-xs-1 tab-neg-margin pull-left"> <a id="sidebar-tab" class="glyphicon glyphicon-chevron-left" href="javascript:void 0;"></a></div><div id="content-container" class="thin-left-border col-sm-9 markdown"><div id="toc" class="toc"></div><div id="doc-content"><h1>Doc Issues</h1><p>This page explains how documentation issues are reviewed and prioritized for the <a href="https://github.com/istio/istio.github.io" target="_blank">istio/istio.github.io</a> repository. The purpose is to provide a way to organize issues and make it easier to contribute to Istio documentation. The following should be used as the standard way of prioritizing, labeling, and interacting with issues.</p><h2 id="categorizing-issues">Categorizing issues</h2><p>Issues should be sorted into different buckets of work using the following labels and definitions. If an issue doesnt have enough information to identify a problem that can be researched, reviewed, or worked on (i.e. the issue doesnt fit into any of the categories below) you should close the issue with a comment explaining why it is being closed.</p><table><tr><td>Needs Clarification</td><td><ul><li>Issues that need more information from the original submitter to make them actionable. Issues with this label that aren't followed up within a week may be closed.</li></ul></td></tr><tr><td>Actionable</td><td><ul><li>Issues that can be worked on with current information (or may need a comment to explain what needs to be done to make it more clear)</li><li>Allows contributors to have easy to find issues to work on</li></ul></td></tr><tr><td>Needs Tech Review</td><td><ul><li>Issues that need more information in order to be worked on (the proposed solution needs to be proven, a subject matter expert needs to be involved, work needs to be done to understand the problem/resolution and if the issue is still relevant)</li><li>Promotes transparency about level of work needed for the issue and that issue is in progress</li></ul></td></tr><tr><td>Needs Docs Review</td><td><ul><li>Issues that are suggestions for better processes or site improvements that require community agreement to be implemented</li><li>Topics can be brought to SIG meetings as agenda items</li></ul></td></tr><tr><td>Needs UX Review</td><td><ul><li>Issues that are suggestions for improving the user interface of the site.</li><li>Fixing broken site elements</li></ul></td></tr></table><h2 id="prioritizing-issues">Prioritizing Issues</h2><p>The following labels and definitions should be used to prioritize issues. If you change the priority of an issues, please comment on the issue with your reasoning for the change.</p><table><tr><td>P1</td><td><ul><li>Major content errors affecting more than 1 page</li><li>Broken code sample on a heavily trafficked page</li><li>Errors on a “getting started” page</li><li>Well known or highly publicized customer pain points</li><li>Automation issues</li></ul></td></tr><tr><td>P2</td><td><ul><li>Default for all new issues</li><li>Broken code for sample that is not heavily used</li><li>Minor content issues in a heavily trafficked page</li><li>Major content issues on a lower-trafficked page</li></ul></td></tr><tr><td>P3</td><td><ul><li>Typos and broken anchor links</li></ul></td></tr></table><h2 id="handling-special-issue-types">Handling special issue types</h2><p>If a single problem has one or more issues open for it, the problem should be consolidated into a single issue. You should decide which issue to keep open (or open a new issue), port over all relevant information, link related issues, and close all the other issues that describe the same problem. Only having a single issue to work on will help reduce confusion and avoid duplicating work on the same problem.</p><p>Depending on where a dead link is reported, different actions are required to resolve the issue. Dead links in the reference docs are automation issues and should be assigned a P1 until the problem can be fully understood. All other dead links are issues that need to be manually fixed and can be assigned a P3.</p></div></div></div></div></div></div><script src="/v0.2/js/sidemenu.js"></script><footer><div class="container"><div class="row"><div class="col-md-2"></div><div class="col-md-3 col-sm-4 col-xs-12 center-block"><ul class="toggle"><p class="header">Docs</p><li><a href="/v0.2/docs/">Welcome</a></li><li><a href="/v0.2/docs/concepts">Concepts</a></li><li><a href="/v0.2/docs/setup">Setup</a></li><li><a href="/v0.2/docs/tasks">Tasks</a></li><li><a href="/v0.2/docs/guides">Guides</a></li><li><a href="/v0.2/docs/reference">Reference</a></li></ul></div><hr class="footer-sections" /><div class="col-md-3 col-sm-4 col-xs-12 center-block"><ul class="toggle"><p class="header">Resources</p><li><a href="/v0.2/faq">Frequently Asked Questions</a></li><li><a href="/v0.2/troubleshooting">Troubleshooting Guide</a></li><li><a href="/v0.2/bugs">Report a Bug</a></li><li><a href="https://github.com/istio/istio.github.io/issues/new?title=Issue with _docs/reference/contribute/reviewing-doc-issues.md">Report a Doc Issue</a></li><li><a href="https://github.com/istio/istio.github.io/edit/master/_docs/reference/contribute/reviewing-doc-issues.md">Edit This Page on GitHub</a></li></ul></div><hr class="footer-sections" /><div class="col-md-3 col-sm-4 col-xs-12 center-block"><ul class="toggle"><p class="header">Community</p><li><a href="https://groups.google.com/forum/#!forum/istio-users" target="_blank"><span class="group">User</span></a> | <a href="https://groups.google.com/forum/#!forum/istio-dev" target="_blank">Dev</a> | <a href="https://github.com/istio/istio/blob/master/GROUPS.md#working-groups" target="_blank">Working Group Lists</a></li><li><a href="https://twitter.com/IstioMesh" target="_blank"><span class="twitter">Twitter</span></a></li><li><a href="https://github.com/istio/istio" target="_blank"><span class="github">GitHub</span></a></li></ul></div><div class="col-md-1"></div></div><div class="row"><p class="description small text-center"> Istio 0.2, Copyright &copy; 2017 Istio Authors<br> Archived on 12-Nov-2017</p></div></div></footer><script src="https://cdnjs.cloudflare.com/ajax/libs/jquery-validate/1.15.0/jquery.validate.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery.form/4.2.1/jquery.form.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery-visible/1.2.0/jquery.visible.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/jqueryui/1.12.1/jquery-ui.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/slick-carousel/1.6.0/slick.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/1.7.1/clipboard.min.js"></script> <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js"></script> <script src="/v0.2/js/common.js"></script> <script src="/v0.2/js/buttons.js"></script> <script src="/v0.2/js/search.js"></script> <script src="/v0.2/js/prism.js"></script></body></html>