your_guide_to_collaborate_in_a_wg.md

Your Guide to Collaborate in GSF WGs

This guide is aimined to the collaborators of the GSF Working Groups. It provides a simple explanation of the GSF process as well as the tasks that you will perform when collaborating in any of the GSF Working Groups.

If you want to gain a better understanding of the GSF process and tasks, then we invite you to review these documents:

The Way We Work

• Overall GSF process  

How to Collaborate

Get Familiar with the Rules

This guideine is a brief introduction or checklist to the GSF process. We encourage you to get faimiliar with the documents listed here:

• The Way We Work
• CONTRIBUTING Guidelines
• Release Planning & Editorial Calendar

Meetings Check List

• Check the Agenda content before joining the meeting
• If you have submitted a contribution, make sure that it is listed on the Agenda. Otherwise, at the beginning of the meeting ask the Chair to include your topic to the agenda
• If you have a topic that you would like to be added during the call, then ask the chair if the topic can be added to the "Any Other Business" (AOB) section of the Agenda. Topics in this section are taking as time permits
• Normally, Working Group meetings follow a “raise your hand” process to speak during the meeting. The chair will call your name when is your turn to speak

Presenting a contribution in a Meeting

• The chair will normally allocate a time slot to each contribution in the agenda
• If you are presenting a document (contribution), be respectful of your allocated time. If you need an extension, ask the Chair for more time but be thoughtful about other members' presentation slots
• If your contribution receives comments, make sure that you understand them, and try to accommodate them within the spirit of your contribution
• If your contribution, receives an objection:
  • Contributions that have received an objection cannot be approved before the objection is resolved
  • DONT's
    • Don’t engage in a heated discussions with the group or a particular person
  • DO's
    • Understand the objection and aim to provide a resolution that meet both views; yours and the person that submitted the objection
    • If the discussion is taking too much meeting time, invite the other party or parties to join an offline discussion to resolve the objection
  • If the objection is not resolved and it is not withdrawn, then the only possible solutions are or withdraw the contribution or ask the Chair for a Vote on the contribution
    • Votes in Standards Organizations are highly discouraged. There is no a winner when a contribution has to be enforced by a Vote.
    • See “Decision Making” section in the “The Way We Work”

Review & Approval Process

This is the process followed by the Group to decide if a particular contribution is accepted or not. This process contains:

• Review & Approval Period
• Comments or Objections
• Resolution Criteria

Review & Appoval Period

• Is the time allocated by the Chair (with the agreement of the group) during which comments or objections can be submitted
  • The Working Group needs to decide the length of the Review Period to be allocated to each contribution
• Normally the period goes between 0 to 15 days, depending of the complexity of the contribution
• Each contribution should be classified by the group:
• Contribution Types
  • Normally contributions are classified according to the type of changes:
    • Editorial
      • These contributions are characterized for addressing changes that don't alter the meaning of the material
      • Editorial changes include punctuation changes, grammar corrections, reordering existing material and adding headers for easing of use, and hyperlink additions or misspells corrections
    • Minor
      • This type is used for contributions that introduce changes that enhance or provide a better explanation to existing functions. It can be used also to introduce new functionality that is not considered a core function or a big change on the behaviour of the system
    • Major*
      • This type is used for contributios that alters the form, fit or, function, of the artifact that is under development. It could be apply to new core functionalities or changes to an existing ones.

Comments or Objections

• This represents the input provided by members of the Working Group
• This input is classified in two types:

  • Comments

    • A comment implies that the submitter is in agreement with the contribution but she suggests some enhancements to be considered
      • These enhancemnts may or may not be incorporated by the owner of the contribution
    • If the comments, contain a question
      • The question needs to be resolved before the Working Group accepts the contribution

  • Objection

    • An Objection is a comment provided by a submitter that represents a disagrement with the contribution
    • The submitter of the objection needs to clearly indicate that she is objecting to the approval of the contribution as currently is formulated
    • The submitter of an objection MUST provide a clear explanation for the objection and it should contain a suggestion on how it can be addressed
    • Comments marked as Objections MUST be discussed by the Working Group before finalizing the status of the contribution

Resolution Criteria

• Based on the type of contribution:
  • Editorial contributions
    • Normally are not requested to be included in a Review & Approval Period
    • They can ber incorporated (merged) by the Editor, Chair or Maintainer without the need to be subject to a Review and Approval Review
• The rest of contributions are subject to a Review and Approval Period:
  • Minor contributions
    • The group may agree that contributions marked as Minor need to:
      • Be placed in a 3 days Review and Approval Period, and
      • Must receive three (3) Ok from the members in order to be considered as Approved
  • Major contributions
    • The group may agreed that contributions marked as Major need to:
      • Be placed in a 5 days Review and Approval Period, and
      • Must receive three (3) Ok from the members in order to be considered as Approved
• Contributions marked as Approved, can be merged by the Editor, Chair or Maintainer

How to Develop Content

Type of Content

• The Working Group may develop three different type of content:
  • Software Code
  • Whitepaper
  • Technical Specifications

Work Package Life-Cycle

Work Package Phase

• The Work Packages defined by the Working Group must be aligned with the Scope of the Working Group. Otherwise, legal concerns may arise
• Each Work Package should be brokend down into one or small components. These components should be broken further down into features.
• The Working Group should agree which features will be allocated to a particular Release version X.Y.Z. See Semantic Versioning
• Each Release should be added to the Release Planning with a delivery date and the set of features covered by the Release
• Once the Working Group agrees the the content of the Release, no further features should be added. If a new feature is under consideration, the group should evaluate if that new feature should be part of the next Release features

Development Phase

	Code	Technical Specifications	Whitepaper
Templates	Software License Template	Requirements Architecture Technical Specifications	Whitepaper
GitHub Flow	Suggested Single-Trunk Based Development
Review & Approval type of change	Editorial: merged - inmediately - by Editor, Chair, Maintainer
	Minor: 1, 2, or 3 days Review Period & Receive 3 Ok's from the members
	Major: 4 or 5 days Review Period & Receive 3 Ok's from the members

Consistency Review & Approval Phase

• At the end of the Development phase, the developed content should be submitted to a Final Review & Approval called Consistency Review
• This Consistency Reivew should last 1 or 2 weeks
• During this period, members of the Working Group should review and provide comments in order to validate the consistency of the content under review
• All the comments received should be recorded and resolved by the Working Group before sending the output to a Final Working Group Approval
• Once all the comments received during the Consistency Review have been Closed the Chair will open a Final Review & Approval to formally Approve the output or deliverable
  • The Review Period for this Final Approval is decided by the Chair in consultation with the Working Group
• Once the output or deliverable produced by the Working Group is Finally Approved the Chair will send the output to the Steering Committee for Ratification
• The Editor or Maintainer may need to provide some final changes to the document, i.e. marked the document as formally Approved

Steering Committee Ratification Phase

• The Steering Committee Ratification is an administrative process where the Organization acknowledge that an output produced and Approved by a Working Group is about to be published on behalf of the Organization
  • This step is necessary as it bounds the Organizaion members with the legal framework defined in the output

Preparation & Publication Phase

• Upon Steering Committee Ratification the output produced by the Working Group should be made publicly available
• Options to Publish content via GitHub:
  • Update GitHub Pages with the content or links to the content in the case of Code
  • Automated Document Generation
    • Whitepapers and Technical Specifications should be made available in:
      • Markdown format that is rendered by GitHub.com platform
      • PDF and HTML formats via GitHub Pages
        • There are several mechanisms to easily convert markdown into PDF and HTML

Public Feedback

• The Editorial Calendar will contain the promotional artifacts for each output produced and published by the Working Groups
• GitHub Pages should be used to collect feedback from the members of the public
  • This feedback could be left via webforms or GitHub Issues
  • References to the feedback should be included in the corresponding Working Group Agenda for group review