Second Screen/Work Mode
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.
Contents
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:
- Familiarize yourself with the group's Charter
- Review the group's specification(s): see Publication Status
- Participate in discussions on the group's mailing list: public-secondscreen@w3.org (usage guidelines)
- Give feedback on the spec(s), propose changes, discuss new features, etc.
- Review, help resolve open issues (see Issues)
- You may use the GitHub comments feature, or post to the mailing list
- Review Pull Requests
- Make direct spec contributions
- Attend the group's formal meetings
If you are not a group Participant, you can:
- Participate via the group's public public mailing list (public-secondscreen@w3.org) to provide comments and contributions that are consistent with the W3C Patent Policy.
- If you are interested in making substantial technical contributions and are not yet a group participant, please join the Second Screen Working Group (or talk to your W3C Advisory Committee representative).
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 group's specifications are in GitHub, open for contributions:
- Presentation API: GitHub w3c/presentation-api
- Remote Playback API: GitHub w3c/remote-playback
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.
- Install GNU Make if not already present (this is optional, see how to contribute instructions below):
- On Linux and MacOS,
make
is usually installed with compiler tools - On Windows, the easiest option is probably to use Win-Builds:
- Follow the Windows instructions and run the package manager in particular
- 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) - Open a terminal and
cd
to theWin-Builds\bin
folder - Run
yypk-1.5.0.exe --web --packages make
(version number may need to be adjusted depending on the version you installed) - 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 aC:\bin
folder and that it is in your path - (If you do not want to use Win-Builds, you may download the source code of GNU Make and build it using Visual Studio)
- (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)
- On Linux and MacOS,
- Retrieve the code of the specification:
- Fork the https://github.com/w3c/presentation-api repository
- Clone your fork (replace
YOUR_GITHUB_USERNAME
with your GitHub username):-
git clone https://github.com/YOUR_GITHUB_USERNAME/presentation-api.git && cd presentation-api
-
- 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):-
git remote rename origin YOUR_FORK_NAME
-
- Add the upstream repository as a remote with a name
w3c
:-
git remote add w3c https://github.com/w3c/presentation-api
-
git fetch --all
-
- You should now have two remotes,
YOUR_FORK_NAME
andw3c
, to see the list of remotes:-
git remote -v
-
- Your environment has been setup and you're ready to start contributing \o/
- (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.
- Before doing any local changes, it is a good idea to ensure your fork is up-to-date with the upstream repository:
-
git fetch w3c
-
git merge w3c/gh-pages
-
- In the
presentation-api
directory, update the spec sourceindex.html
with your changes. - To clean up the specification with HTML tidy:
- If GNU Make is available, simply type:
make
- If you chose not to install GNU Make, type:
tidy -config build/tidyconfig.txt -o index.html index.html
- If GNU Make is available, simply type:
- If no errors were reported,
index.html
now contains a cleaned up version of the spec with your changes. - Review your changes:
-
git diff
-
- Stage changes to the spec source:
-
git add index.html
-
- Commit the changes to your local repository:
-
git commit -m "Your commit message"
(see how to write a Git commit message)
-
- 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 defaultgh-pages
branch):-
git push YOUR_FORK_NAME gh-pages
- (Note: use the default
gh-pages
branch for minor changes only. For more significant changes, please create a new branch instead.)
-
- On GitHub, navigate to your fork
https://github.com/YOUR_GITHUB_USERNAME/presentation-api
and create a pull request with your changes. - 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:
- 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:
- Ensure its local fork of the Git repository is up-to-date
- Switch to the
TR
branch and merge thegh-pages
into it - Push the
TR
branch to the repository on GitHub - Travis CI should detect the push and send the right publication request to Echidna, the new publication tool at W3C
- ☑ 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 ascrEnd
as needed
- Update
- ✔ 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
- Setup Test Environment
- fork the https://github.com/web-platform-tests/wpt repository
- Clone your fork (replace
YOUR_GITHUB_USERNAME
with your GitHub username):-
git clone --recursive https://github.com/YOUR_GITHUB_USERNAME/wpt.git && cd wpt
-
- Configure Remote / Upstream to keep your forked local copy up-to-date with the latest commits in the W3C repository
- Add new git remote:
git remote add upstream https://github.com/web-platform-tests/wpt.git
- Fetch remote changes:
git fetch upstream
- Merge them into your local repository:
git merge upstream/master
- Add new git remote:
- Create new branch for your tests
- 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)
- Create branch:
- Write your tests (see "How to write tests")
- Commit changes
- Check added or modified files:
git status
- Add files:
git add [file1] [file2] ... [fileN]
- Commit to your local repository:
git commit -m "short description about your commit"
- Check added or modified files:
- Submit your tests
- Push your changes to your fork:
git push origin YOUR_BRANCH_NAME
- In a browser, open the GitHub page for your forked repository:
https://github.com/YOUR_GITHUB_USERNAME/wpt
- Create a Pull Request
- Wait for feedback on your pull request (you will be notified in the GitHub UI and you may get an email)
- 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.
- Push your changes to your fork:
- How to write tests
- On the web-platform-tests.org you will find a very good documentation on how to write tests.
- More details for Presentation API specific tests is coming soon ...
- How to run tests
- 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).
- 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 - Add the test domains in your host files.
- Start test server:
./wpt serve
. The default ports are8443
(HTTPS) and8000
(HTTP). The instructions to change these ports are available in Running Tests Manually. - 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.
- To run Presentation API tests only enter the path of the Presentation API folder
/presentation-api
in theRun 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
.
- How to review tests
- 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.
- 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.
- For more details please have a look at the Reviewing Tests document.