Second Screen/Work Mode

From W3C Wiki

The purpose of this wiki is to document the Second Screen WG's Real Work Modes, that is, best practices how to get work done.

Note the WG's Charter formally defines the general framework of the group's working mode. In all cases, the Charter and/or the W3C Process Document overrides the information in this wiki. Nevertheless, this wiki contains additional information about how the group really works and as such, this information may be particularly useful to new members of the group.

This document is a Living Document and as such will change. Members of the group are encouraged to edit (e.g. to update, correct, etc.) the information in this document.

Participation

Second Screen Working Group's formal participation and communication models are documented in the Participation and Communications sections of the Charter, respectively.

Formal Participants

As a formal Working Group Participant, you are encouraged to:

If you are not a group Participant, you can:

Spec Editor

The Spec Editor has some additional roles and responsibilities in addition to those of a Formal Participant:

  • Author the specification and ensure it reflects consensus of the group and also considers feedback received from commenters outside the group.
    • Note: landing "work in progress" (WIP) features to the Editor's Draft (ED) early is useful for soliciting wider feedback. The Editor may land WIP features to the Editor's Draft spec early ("edit first review later") if they are clearly marked as such e.g. by linking back to the GH issue to indicate instability.
  • Make sure there is a timely response to the feedback that is submitted to the specification(s) s/he is editing. Note: the response does not need to be from the Editor.
  • As the specification advances on the W3C Rec Track, work with the Chair and the W3C Team to make sure the spec remains ready for publication (pass Markup Validation, Pubrules, Link Checker)
  • Publish new Working Draft versions periodically as the Editor's Draft evolves. See Publication as Working Draft for details.
  • Keep the Publication Status up-to-date.
  • Ensure the issue tracker is up-to-date and in sync with the specification (e.g. ensure unaddressed feedback sent to the mailing list has a corresponding issue), assign priority labels, identify issues that are blocking a milestone (spec publication).
  • More helpful resources for editors are available in the WebApps WG's spec editing.

Test Facilitator

The person(s) responsible for maintaining a specification's test suite, including updating test cases, making sure test cases contributed by others are reviewed properly. A Test Facilitator should create an Implementation Report (for examples, see implementation reports).

Direct Spec Contributions

The Spec Editor is the person in charge of ensuring the specification reflects the group's consensus. In practice this means he is responsible for integrating changes proposed by the group into the spec and ensuring the specification meets the requirements expected from a W3C Recommendation Track deliverable.

The instructions that follow use the Presentation API as an example. For the group's other specifications, simply replace presentation-api with the repo name.

Participants who prefer to make more direct contributions may make spec contributions via pull requests, see How to Contribute via Pull Requests for guidance specific to this group.

For more general guidance, see:

How to Setup the Environment

The group uses ReSpec for specification authoring, HTML Tidy (binaries) to clean up the specification source, a GNU Make makefile for controlling HTML Tidy, and the spec itself is in GitHub at https://github.com/w3c/presentation-api. There are couple of steps you should take to setup the environment.

  1. Install GNU Make if not already present (this is optional, see how to contribute instructions below):
    1. On Linux and MacOS, make is usually installed with compiler tools
    2. On Windows, the easiest option is probably to use Win-Builds:
      1. Follow the Windows instructions and run the package manager in particular
      2. Exit the GUI without installing anything (you may use the Win-Builds GUI but all tools are selected by default and make is the only package needed in practice)
      3. Open a terminal and cd to the Win-Builds\bin folder
      4. Run yypk-1.5.0.exe --web --packages make (version number may need to be adjusted depending on the version you installed)
      5. Rename the bin\gmake.exe binary and place it to your path, e.g. copy bin\gmake.exe C:\bin\make.exe, supposing you have a C:\bin folder and that it is in your path
      6. (If you do not want to use Win-Builds, you may download the source code of GNU Make and build it using Visual Studio)
      7. (Note: unless the binary gets updated to a newer version, do not install the GNU Make binary from Make for Windows. Version 3.81 of GNU Make crashes on recent versions of Windows due to path issues)
  2. Retrieve the code of the specification:
  3. Fork the https://github.com/w3c/presentation-api repository
  4. Clone your fork (replace YOUR_GITHUB_USERNAME with your GitHub username):
    1. git clone https://github.com/YOUR_GITHUB_USERNAME/presentation-api.git && cd presentation-api
  5. Give your remote a more descriptive name (replace YOUR_FORK_NAME with a name you'd like to give to your repository, could be your GitHub username, for example):
    1. git remote rename origin YOUR_FORK_NAME
  6. Add the upstream repository as a remote with a name w3c:
    1. git remote add w3c https://github.com/w3c/presentation-api
    2. git fetch --all
  7. You should now have two remotes, YOUR_FORK_NAME and w3c, to see the list of remotes:
    1. git remote -v
  8. Your environment has been setup and you're ready to start contributing \o/
    1. (If you run into issues in setting up the environment, please ask guidance on the mailing list, or ping the chair or the spec editor directly.)

How to Contribute via Pull Requests

Direct contributions to the spec should be made using the Fork & Pull model. The presentation-api directory contains the spec source (index.html), Makefile, and the configuration files needed to generate the spec.

  1. Before doing any local changes, it is a good idea to ensure your fork is up-to-date with the upstream repository:
    1. git fetch w3c
    2. git merge w3c/gh-pages
  2. In the presentation-api directory, update the spec source index.html with your changes.
  3. To clean up the specification with HTML tidy:
    1. If GNU Make is available, simply type:
      make
    2. If you chose not to install GNU Make, type:
      tidy -config build/tidyconfig.txt -o index.html index.html
  4. If no errors were reported, index.html now contains a cleaned up version of the spec with your changes.
  5. Review your changes:
    1. git diff
  6. Stage changes to the spec source:
    1. git add index.html
  7. Commit the changes to your local repository:
    1. git commit -m "Your commit message" (see how to write a Git commit message)
  8. Push your changes up to your GitHub fork (assuming YOUR_FORK_NAME is the name of your remote, and you are working off of the default gh-pages branch):
    1. git push YOUR_FORK_NAME gh-pages
    2. (Note: use the default gh-pages branch for minor changes only. For more significant changes, please create a new branch instead.)
  9. On GitHub, navigate to your fork https://github.com/YOUR_GITHUB_USERNAME/presentation-api and create a pull request with your changes.
  10. Assuming there are no concerns from the group in a reasonable time, the editor will merge the changes to the upstream w3c/presentation-api repository, and the Editor's Draft hosted at https://w3c.github.io/presentation-api/ is automatically updated.

How to Merge Pull Requests

Pull requests often contain work-in-progress commits such as "fix typos" or "oops" commits, that do not need to be retain in the Git history of the main branch. By default, the editor will merge such pull requests with the Squash and merge option provided by GitHub to create only one commit in the Git history.

Issues

  • The recommended and preferred mechanism for tracking spec issues/bugs is to use the GitHub's issue tracker. Some issues are also highlighted in the spec inline to provide more context around them.

Opening a New Issue

If you identify a spec bug, typo, or have a more substantial proposal, you are encouraged to open an issue to make sure there's a paper trail and the issue does not go unnoticed:

  1. Open a new issue (after checking the existing issues for duplicates)

Resolving Issues

All group participants are encouraged to resolve open issues. There are couple of ways how you can help the group shorten its open issues list:

  • Pull requests provide the most direct way of doing spec contributions (see "How to Contribute via Pull Requests) -- if you'd like to land your change fast PRs are often the fastest way to do so. You can include keywords in your commit messages to automatically close issues in GitHub, see closing issues via commit messages.
  • If you feel your proposal is not well-baked yet, you are encouraged to propose your straw man in the issue comments, or send it to the mailing list public-secondscreen@w3.org, linking back to the GH issue.

It is good practice to let the group know that you are working or intend to work on an issue. However, please note that GitHub does not allow you to assign issues to yourself unless you are in the list of contributors for the repository. Get in touch with François to be added to the list (make sure your GitHub username appears in the email). Or just simply say in issue comments you're planning to work on it.

Priorities

The group is encouraged to assign priority labels to issues. The primary responsibility is on the editor to ensure the issue priorities reflect the group's consensus. However, any group participant is encouraged to help with bug triage by suggesting changes on the mailing list or in the issue tracker comments. Participants interested in contributing more closely can be granted access to the issue tracker upon consideration by the chair.

  • The following labels are currently used:
  • P1 = major issues that need to be resolved sooner than later, usually blockers for implementations
  • P2 = minor issues that should be looked at at some point
  • P3 = editorial issues or feature requests, nothing really blocking

To give more context, other labels (bug, duplicate, enhancement etc.) may be used.

Milestones

The group may create milestones that map to the standards track stages (First Public Working Draft, Last Call, Candidate Rec etc.) and associate the issues with the milestones. Please note that any milestone "Due by" dates are provisional.

Actions

GitHub issue tracker provides means to add assignees to issues. If you are assigned an issue, take this as a hint that you are expected to take an action to address the issue. The participants are encouraged to self-assign issue to themselves to prevent surprises and overcommitting.

To track admin actions or actions that do not map directly to open spec issues e.g. “Review the latest Editor's Draft” or “Investigate whether X is possible on the platform Y”, "Ask the group Z for feedback" the group may use the W3C Tracker (note: not setup yet, we'll need to figure out if we actually need this).

Publication as Working Draft

The GitHub repository contains the latest Editor's Draft of the specification. This draft is published as a Working Draft in W3C's Technical Reports (TR) space periodically. The latest published Working Draft is available at http://www.w3.org/TR/presentation-api/. The Second Screen Working Group resolved to switch to the new publication workflow to streamline the publication of Editor's Drafts to TR space.

The Spec Editor is the person in charge of publishing new versions of the specification as Working Drafts.

To publish a new Working Draft, the Spec Editor should run the following steps:

  1. Ensure its local fork of the Git repository is up-to-date
  2. Switch to the TR branch and merge the gh-pages into it
  3. Push the TR branch to the repository on GitHub
  4. Travis CI should detect the push and send the right publication request to Echidna, the new publication tool at W3C
  5. ☑ Check the result of the publication on the public-tr-notifications@w3.org mailing list archives and ensure the latest Working Draft has been updated.

If Echidna refuses to publish the document, test the document with Pubrules Checker with the following settings:

  • URL: spec-generator provided spec URL
    • Update publishDate to match the expected publication date, add other metadata such as crEnd as needed
  • ✔ Check that the document is valid for automatic publication with Echidna

Fix any errors, and try publishing it again. The main Git commands to issue to publish a new version should thus be: 

git checkout TR
git merge gh-pages
git push w3c TR

Testing

Like other W3C APIs, the Web Platform Tests Project is used to test the Presentation API. The Web Platform Tests Project is a W3C-coordinated attempt to build a cross-browser testsuite for the Web-platform stack. Each W3C API has its own test folder in the main project. The presentation API tests are available in the /presentation-api folder.The Presentation API folder contains two subfolders /presentation-api/controlling-ua and /presentation-api/receiving-ua for testing the API in controlling and receiving user agents.

Contribution

  1. Setup Test Environment
    1. fork the https://github.com/web-platform-tests/wpt repository
    2. Clone your fork (replace YOUR_GITHUB_USERNAME with your GitHub username):
      1. git clone --recursive https://github.com/YOUR_GITHUB_USERNAME/wpt.git && cd wpt
    3. Configure Remote / Upstream to keep your forked local copy up-to-date with the latest commits in the W3C repository
      1. Add new git remote: git remote add upstream https://github.com/web-platform-tests/wpt.git
      2. Fetch remote changes: git fetch upstream
      3. Merge them into your local repository: git merge upstream/master
    4. Create new branch for your tests
      1. Create branch: git checkout -b YOUR_BRANCH_NAME (replace YOUR_BRANCH_NAME with something that describes specifically what you are testing e.g. presentation-api-idlharness if you are adding new IDL tests of the Presentation API)
    5. Write your tests (see "How to write tests")
    6. Commit changes
      1. Check added or modified files: git status
      2. Add files: git add [file1] [file2] ... [fileN]
      3. Commit to your local repository: git commit -m "short description about your commit"
    7. Submit your tests
      1. Push your changes to your fork: git push origin YOUR_BRANCH_NAME
      2. In a browser, open the GitHub page for your forked repository: https://github.com/YOUR_GITHUB_USERNAME/wpt
      3. Create a Pull Request
      4. Wait for feedback on your pull request (you will be notified in the GitHub UI and you may get an email)
      5. Once your pull request is accepted, delete your branch. This can easily be done in the GitHub UI by navigating to the pull requests and clicking the 'Delete Branch' button.
  2. How to write tests
    1. On the web-platform-tests.org you will find a very good documentation on how to write tests.
    2. More details for Presentation API specific tests is coming soon ...
  3. How to run tests
    1. Setup test environment as described above (If you only want to run existing tests, you can use the w3c test server (https://w3c-test.org/) without the need to setup the test environment locally. In this case, you can skip the next three steps and continue with step 5).
    2. Check test domains: ./wpt make-hosts-file. The list of test domains like the following example will be shown:
      127.0.0.1 xn--lve-6lad.not-web-platform.test
      127.0.0.1 xn--lve-6lad.web-platform.test
      127.0.0.1 xn--n8j6ds53lwwkrqhv28a.not-web-platform.test
      127.0.0.1 www1.web-platform.test
      127.0.0.1 www2.web-platform.test
      127.0.0.1 not-web-platform.test
      127.0.0.1 web-platform.test
      127.0.0.1 www2.not-web-platform.test
      127.0.0.1 www1.not-web-platform.test
      127.0.0.1 www.not-web-platform.test
      127.0.0.1 www.web-platform.test
      127.0.0.1 xn--n8j6ds53lwwkrqhv28a.web-platform.test
    3. Add the test domains in your host files.
    4. Start test server: ./wpt serve. The default ports are 8443(HTTPS) and 8000(HTTP). The instructions to change these ports are available in Running Tests Manually.
    5. Open test runner in the Browser you are going to test: use https://web-platform.test:8443/tools/runner/index.html to run tests from local test server or https://w3c-test.org/tools/runner/index.html to run tests from W3C test server. The first time you use this it has to generate a manifest of all tests which may take some time. More details are available on the Web Platform Tests project on GitHub.
    6. To run Presentation API tests only enter the path of the Presentation API folder /presentation-api in the Run tests under path input field of the test runner page from previous step. To run Presentation API tests for only controlling user agent enter /presentation-api/controlling-ua and for only receiving user agent enter /presentation-api/receiving-ua.
  4. How to review tests
    1. The reviewer can be anyone (other than the original test author) that has the required experience with both the spec under test and with the General Test Guidelines.
    2. As review Tool the group decided to use GitHub UI for code review and not Critic which has a steeper learning curve than the GitHub tools.
    3. For more details please have a look at the Reviewing Tests document.
Retrieved from "https://www.w3.org/wiki/index.php?title=Second_Screen/Work_Mode&oldid=106713"