New Datatracker Chartering Procedure for Chartering New Working Groups

This is an exhaustive record of the steps I took to charter dnssdext, presented as a list of instructions. The idea is to edit this down to a guide to the current process for creating working groups using the new datatracker. Current documentation on chartering working groups describes a very manual process with little datatracker interaction and a lot of work for the secretariat which is no longer necessary.

Starting condition: Bof process completes, with BoF chairs proposing a charter for a new working group.

  1. Go to datatracker, log in, choose "Chartering WGs" from the list of options on the left, towards the bottom of the Working Groups box. [Deborah] If want to reuse BoF name/acronym, can simply go to datatracker's page for the BoF and edit the fields. Otherwise, datatracker will not allow reuse of the name/acronym for chartering a new WG.
  2. At the top of the page, click on the link, Start Chartering New WG
  3. Fill out the form; you do not need to fill out the fields for which you do not yet have information, but you should know the working group name, short name, and probably the name of the responsible AD at this point. Both the working group name and short name can of course be changed later if that comes out as part of the charter review process. See below for more on these fields, and when they should be filled out.
  4. If the name of the working group is the same as the name of the BoF, you will get a warning that you are choosing the same name as the BoF; you don't have to do anything other than resubmit in this case, but only do that if the name clash was expected. [Deborah] Datatracker did not allow me to reuse the name/acronym. It gave the warning, and resubmitting did not allow me to proceed. If want to reuse, need to edit the BoF datatracker page.
  5. You will now see a screen where you can enter charter text. Either cut and paste it into the box, or scroll down to the bottom and upload a text file.
  6. You will now see a page that allows you to edit the message to the secretariat, set the review time, and add comments. You most likely will want to just click the "Initiate chartering" button at the bottom.

If you make any mistakes setting up the working group, you can get to the working group page by again clicking on the Chartering Working Groups link in the Working Groups box at the left side of the datatracker page. Click on the short name of the working group to get to its page. Edit WG will let you make changes to the name of the working group, chairs, mailing lists and links. Or click on the long name of the working group to edit the charter.

It is very important at this juncture to look at how the charter was formatted by the datatracker. It is frequently the case that the datatracker formatting will get into an argument with whatever formatting you have done, and wind up producing something that is unpleasant to read. In general, it's probably a good idea to format the text as fixed-width text with a right margin at 72 characters, and to indent bulleted lists and enumerated lists so that the bullet or numeral stands out to the left of the paragraphs.

To bring the working group to the IESG for review, you need to change the charter state—to do this, go to the charter page in the datatracker and click on the link to the right of the Charter State heading (it will read "Informal IESG Review" when the charter has been newly added). To begin IESG review, change the state to "Internal Review." Click on "Save and (possibly) notify Secretariat."

Note: As of this writing, when you click on this state after newly adding the proposed working group, you will see a warning in red at the bottom of the page: "Warning: Announced initial review time hasn't elapsed yet. It does so at 2013-09-21 08:21." You should disregard this warning—it's a glitch in the datatracker, not a part of the actual working group chartering process.

Note: As of this writing, when you change the state to internal review, the datatracker adds a note to the secretariat that says "Please place it on the next IESG telechat and inform the IAB." You can (and should) place the review on the IESG agenda yourself—there is no need to wait for the secretariat to do it. There is no need to take action to notify the IAB—as part of setting the working group up for review, the secretariat will be notified, and will notify the IAB.

This brings you back to the charter review page. You will see a note, "Not on agenda of IESG telechat." Click on that, and it will bring you to a new page where you can choose which telechat's agenda to add the review to. Choose date and click Save.

Now click on the IESG Writeups tab just below the charter title. This will bring you to a page with a bunch of writeups; scroll down to the bottom and click "Generate Ballot Announcement." Edit the template to put in the information you think the IESG needs to evaluate the working group charter.

Note: This currently generates a ballot announcement template for a draft under review. So you pretty much have to delete that and write down what you think needs to be said. Then click on "Save and send ballot to IESG".

Finally, go back to the charter review page and click on the IESG Review tab. Click on the Edit Position link. Vote yes (presumably you mean to vote yes, or you wouldn't have proposed the new working group for review). You can add a note here if you want, and you have the option of sending it to the IESG.

External review: when does document go from external review to IESG review. Answer: when the external review time expires. When is the ballot issued? When it goes to IESG review. Check when going through this process and update. Tools: should ballot be automatically issued when the state changes to external review? The consensus appears to be yes.

If a typo needs to be fixed, or there's a simple change to the charter, internal review may be more appropriate than external review. _Really_ trivial changes can be addressed with email to the secretariat.

After the IESG has approved the charter following external review, the working group is approved. Before the working group can become active, it's important to make sure that the mailing list is set up with the desired name (see below). Once everything is correct, send mail to the IESG, bcc the secretariat, indicating that the working group is approved.

Note: I think the secretariat moves the working group into the active state, but I'm not sure. It could be done in the UI by the responsible AD. Let's see what happens.

Fields in the Working Group Editor

FieldDescriptionNeeded By
WG NameThe long name of the working group—should describe what the working group is for.Start of chartering
WG AcronymThe short name of the working group—this is what people normally use to refer to the working group, and is often some fairly silly acronym.Start of chartering|
WG StateThe current state of the working group. For a newly proposed working group, this is Proposed; for an existing working group being rechartered, it's Active.Set to Proposed at start of chartering
WG ChairsA list of working group chairs.This does not need to be determined at the beginning of the chartering process, and indeed doing so may be premature. However, by the time the working group is approved, it should have chairs, or it can't do any work.
WG SecretariesA list of working group secretaries (usually zero or one).Not required, but allowed at any point in the process
WG Technical AdvisorsA list of technical advisors to the working group.Not required, but typically determined during the charter review process in the IESG.
Shepherding ADNormally this can be set to the name of the AD who is setting the working group up to be chartered.Start of chartering
IETF AreaThe area in which the working group will be managed.Before the working group becomes active
List EmailThe mailing list on which the business of the new working group will be transacted. Mailing lists are required for BoFs? to be approved, so typically there will already be a mailing list. However, it is desirable to have the mailing list name and the working group name be the same, and BoF names are often different than the final name of the working group, so it may be best to wait until the new working group has been approved before setting up the mailing list.Before the working group becomes active
List SubscribeAn email address to which subscribe requests can be sent.When List Email is determined
List ArchiveThe URL of the mailing list archive for the working group.When List Email is determined
Other URLsBe sure to follow the formatting note under the text box for this field! This field contains URLs that will be useful to IETF participants and others who want to know about the working group. Typically a link to the Jabber room and the Jabber archives for the BoF sessions will be placed here. If the BoF mailing list has a different name than the working group, a link to the BoF mailing list archives should be included here, and if there is a jabber log for the BoF, that should also be included.As available

Charter Review Issues Relating to Milestones

We discussed in the informal telechat on 9/19 how to tweak the process to deal with the problem of milestones in the charter.

It was generally agreed that milestones were not part of the IETF or IESG review process, and therefore that the idea that they are required in order to evaluate a charter is wrong—rather, if what is in the milestones is required to evaluate the charter, it needs to be in the text of the charter.

The question came up as to whether milestones ought to go out with the charter in the email; one proposal was to include them, but put text over them saying "these are just proposed milestones, for your information. They are not part of the charter, and can be changed without further notice to the IETF. If reviewers feel the charter is not sufficient without the milestones, they should propose changes to the charter to address this problem. Or something like that—that's a bit long-winded.

Finally it was mentioned that since what's in the email may not be the latest version, maybe the email should not contain the charter, but rather a pointer to the charter review page. There was some agreement that this was a good idea, but Jari pointed out that this doesn't give the reader of the announcement any clue as to whether they should go look at the charter. So it was further proposed that charters ought to have abstracts, just like documents, and that the abstract should appear in the announcement.

So the path forward seems to have a couple of components:

  • Tools should be updated now so that if charter and milestones are included in the announcement, text about the milestones not being part of the contract should be included.
  • As a side issue, generating the announcement at a different time than it's sent can create issues if the milestones are updated in between, so shouldn't the review announcement be generated when it's sent, rather than at some time previously? This would necessitate a tools change.
  • We would like to investigate the abstract idea. It seems that this would require a change to the datatracker to permit an abstract to be singled out of the charter text, and if the abstract is present, the announcement would just include the abstract and a pointer to the datatracker review page, rather than including the charter and milestones.
Last modified 7 months ago Last modified on 17/01/20 19:17:58