Ticket #3111 (closed documentation: fixed)

Opened 6 years ago

Last modified 6 years ago

Proposed policy: Updating doxygen documentation on master

Reported by: robyn Owned by: robyn
Priority: normal Milestone:
Component: TCT Keywords:
Cc: robyn, mjuric, ktl, rhl, smm, rowen, mfreemon, gpdf Blocked By:
Blocking: Project: LSST
Version Number:
How to repeat:

not applicable

Description (last modified by robyn) (diff)

A Proposal: Updating doxygen documentation on master

Robert Lupton the Good on Jan 2, 2014 emailed the following for TCT consideration

I'd like to propose a new policy, which KT feels that the TCT should discuss:

Developers may fix or augment documentation *on master* whenever they notice something that is unclear. The restrictions would be that:

  1. You may *only* modify comments
  2. You *must* run the unit-tests before pushing
  3. If you are proved to have broken the buildbot build, and we find that you modified something other than comments, you will be harshly reprimanded

Whenever you have any question whatsoever about the correctness of a change you must instead file a ticket as usual, or at least ask a question on "stackoverflow".

I would encourage everyone to look things up on the NCSA master doxygen site (http://lsst-web.ncsa.illinois.edu/~buildbot/doxygen/x_masterDoxyDoc/index.html) and whenever they find something unclear invoke this new policy and FIX IT.

I'm worried that the impedance of creating a ticket, then a branch, then waiting for a review, then doing a merge, then another push, then editing the ticket, would be enough for people not to make the changes. Indeed, that at least the more law-abiding among DM are already not updating docs because of the ticket rules.

Change History

comment:1 Changed 6 years ago by robyn

  • Description modified (diff)
  • Summary changed from Proposed policy: Updating doxygen on master to Proposed policy: Updating doxygen documentation on master

comment:2 Changed 6 years ago by robyn

This proposal was discussed at the TCT Meeting of 30 January 2014 attended by Russell Owen, K-T Lim, Robert Luption, Mario Juric, and Jim Bosch. Mike Freemon sent his regrets since he had no opinion to offer on any of the proposals being reviewed. Gregory Dubois Felsmann sent his regrets but sent his proxy to K-T.

This Policy proposal provoked no adverse opinions. It was accepted unanimously.

K-T was concerned about where this Policy would be documented and how it would be brought to the attention of the developers.

Robyn indicated it would be documented in the Policy page: https://dev.lsstcorp.org/trac/wiki/SwStandards, entitled: 'Software Standards, Policies and Conventions'. Further, it will be advertised by an email reminding developers of that page and highlight the new Policy just included.

This Ticket will be closed when that has been done.

comment:3 Changed 6 years ago by robyn

  • Status changed from new to closed
  • Resolution set to fixed

Policy has been installed PolicyUpdateDoxygenOnMaster, cited on [wiki/SwStandards] and emailed to the masses.

Note: See TracTickets for help on using tickets.