wiki:SacmGitHub

Overview

The SACM working group uses GitHub to track issues against draft documents. Authors/editors are encouraged to also use GitHub to store drafts-in-progress. As of March 2015 we are just getting started with GitHub, so things may change over time. What you'll find here is general guidance on how we expect to use GitHub to our advantage.

We've been able to set up GitHub email notifications so that they are set to sacm@…. Issues and discussions about those issues should happen in GitHub, and they will be sent to sacm@….

Getting Started

To get started using Git Hub for SACM:

  1. Create a Git Hub Account, if you haven't one: https://github.com/. (NOTE: You must have a GitHub account to submit issues.)
  2. Hit this URL: https://github.com/sacmwg

There you'll find several repositories, each relating to one or more of our WG drafts. It's recommended that you subscribe or "watch" the repositories as your interest level dictates. Keep in mind that everything will be sent to the sacm@… mailing list, but you won't be able to reply to GitHub-originated e-mails using the SACM list. If you want to do that, you should subscribe to the repositories and/or watch the issues in which you have an interest.

Workflow

TBD

Creating An Issue

To create an issue, ensure you're logged in to GitHub then:

  1. Navigate to the appropriate repository
  2. Click "Issues"
  3. Click "New Issue"
  4. Enter a descriptive title
  5. Provide details about the issue in the provided text box

Descriptive Titles

This is open-ended, but try to be as descriptive as possible with your title while not being verbose. A title like "Typo" is unhelpful compared to a title like "An ABNF typo exists in section 5". The idea is to provide enough (but just enough) information to let a reader know what's wrong.

Handling An Issue

As an editor/author of a given draft, you will need to be associated with the SACMWG organization (to become associated with the SACMWG organization, contact the WG chairs and provide your GitHub user name). An issue handler will need to:

  1. Choose an appropriate label for the issue
  2. Choose an appropriate milestone for the issue (optional)
  3. Choose an appropriate assignee (note that the assignee does not need to be a document author)
  4. Issues should be closed after the appropriate draft has been posted to the IETF website.

Choosing Labels

An issue can be categorized using labels, and these labels are intended to change as an issue moves through the workflow. The issues we've talked about using on the list can be split into "submission labels" and "handling labels".

Submission Labels:

  • Bug: Use this label if you're submitting an issue proposing a change to existing content
  • Enhancement: Use this label if you're submitting an issue proposing content addition
  • Question: Use this label if you're submitting an issue requesting clarification about some piece of content.

Handling Labels:

  • Duplicate: Set an issue's label to this value if it's a duplicate. It would be a good idea to indicate which issue this one duplicates in the comments.
  • Invalid: Set an issue's label to invalid if it does not apply.
  • Complete: The authors believe that the appropriate edits have been completed for the issue.

Version Labels:

  • A label can be created for each version posted to the IETF website. This allows for better tracking of section numbers as they can change over time and it makes it more difficult to determine what an issue refers to as the section numbers change.

Choosing Milestones

TBD.

Last modified 3 years ago Last modified on Apr 29, 2016, 7:17:32 PM