Editor guidelines

These guidelines are just that, the are to help WG members know how editors intend to work and also help the editors have some common ground.

1 Tools used

We use Mercurial for source control and Respec for document structure and formatting.

Hints/tips for using Mercurial

It is best to pull to get latest changes before starting work, here is a typical sequence that I (Steve) use (illustrating from MacOSX/Linux command line):

1. Check for incoming change sets
   • $hg update
2. If incoming change sets
   1. Receive them
      • $hg pull
3. Do until satisfied with result
   1. Make the intended updates using a local editor
   2. Refresh the file in browser to verify intent
4. Commit locally
   • $hg commit -m "summary of changes" -u userid
5. Push changes to server repo
   • $hg push
6. Simple

2 Using Tracker

It makes sense to use Tracker for certain actions that require a fair amount of change. We indicate which actions are for editing by prefixing them with "[EDITOR]..." and assigning appropriately. If we know which editor is going to make the change, assign to them....if not, then assign to "Unassigned". Once changes have been committed, change the state of the action to "Pending review".

The full flow in theory would be:

1. Working group agrees to resolve an issue
   1. Meeting scribe: Close issue
   2. Meeting scribe or editor: Create action to incorporate closed issue, unassigned Arnaud as owner (see Problems)
   3. Chair: update closed issue with link to resolution in minutes
2. Editor in need of work takes ownership of the action
   1. Editor: Edit Action to assign to self
3. Editor incorporates changes into draft in W3C Mercurial server
   1. Editor: Change Action's state to Pending Review
4. Working group accepts changes
   1. Meeting scribe or editor: close action
5. Working group rejects changes
   1. Editor: Change Action's state to Open

Problems with theoretical workflow:

• 2013-05-17: Create Action with Unassigned owner is not accepted. Use the Chair as proxy for Unassigned.
• 2013-05-17: Editing an action's owner to Unassigned does not remove the former assignee's name from the open/all/etc response. Assigning to a new "not Unassigned" name does change the name.

As of 2013-05-17 14:10 ET, the [EDITOR] actions are believed to be up to date. I.e. for all closed Issues not yet incorporated into the Editor's draft, Actions have been created.

https://www.w3.org/2012/ldp/track/changelog should be useful (thanks Steve) for keeping up with the changes

3 References =

• World Wide Web Consortium (W3C) Process Document
• Info on Mercurial usage
• Mercurial repository URL for this WG
• Respec doc