From 5f2f961e8c476d9c732feb93d5e871e292a071ea Mon Sep 17 00:00:00 2001 From: Vivien Lacourba Date: Fri, 17 Jan 2025 14:20:20 +0100 Subject: [PATCH] Convert W3C on GitHub pages to the new design (#299) This is a follow-up of #267 and #297. --- README.md | 7 +- editor/resources.md | 2 +- github/backup.html | 49 ------ github/backup.md | 17 ++ github/best-practices.html | 300 ------------------------------------ github/best-practices.md | 197 +++++++++++++++++++++++ github/faq.html | 292 ----------------------------------- github/faq.md | 88 +++++++++++ github/git.html | 127 --------------- github/git.md | 67 ++++++++ github/index.html | 122 --------------- github/index.md | 47 ++++++ github/issue-metadata.html | 248 ----------------------------- github/issue-metadata.md | 225 +++++++++++++++++++++++++++ github/repo-management.html | 195 ----------------------- github/repo-management.md | 93 +++++++++++ github/repo-transfer.html | 67 -------- github/repo-transfer.md | 43 ++++++ github/specs.html | 98 ------------ github/specs.md | 41 +++++ github/w3c.json.html | 147 ------------------ github/w3c.json.md | 84 ++++++++++ github/workflow.html | 157 ------------------- github/workflow.md | 69 +++++++++ teamcontact/role.md | 2 +- tools/new-group.md | 6 +- 26 files changed, 978 insertions(+), 1812 deletions(-) delete mode 100644 github/backup.html create mode 100644 github/backup.md delete mode 100644 github/best-practices.html create mode 100644 github/best-practices.md delete mode 100644 github/faq.html create mode 100644 github/faq.md delete mode 100644 github/git.html create mode 100644 github/git.md delete mode 100644 github/index.html create mode 100644 github/index.md delete mode 100644 github/issue-metadata.html create mode 100644 github/issue-metadata.md delete mode 100644 github/repo-management.html create mode 100644 github/repo-management.md delete mode 100644 github/repo-transfer.html create mode 100644 github/repo-transfer.md delete mode 100644 github/specs.html create mode 100644 github/specs.md delete mode 100644 github/w3c.json.html create mode 100644 github/w3c.json.md delete mode 100644 github/workflow.html create mode 100644 github/workflow.md diff --git a/README.md b/README.md index 3b2c3c0d8..458ece1cf 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,8 @@ The general edition of the Guidebook is managed by [@w3c/guidebook](https://gith * How to do wide review. * [/editor/](editor) * How to author a specification, including ReSpec or other spec making programs. +* [/github/](github) + * How to use Git and GitHub at W3C. * [/manual-of-style/](manual-of-style) * The W3C Manual of Style for editors. * [/meetings/](meetings) @@ -45,9 +47,4 @@ The general edition of the Guidebook is managed by [@w3c/guidebook](https://gith * [/other/](other) * Related to [permanent groups](https://www.w3.org/groups/). -# Related repositories -* [//w3c.github.io](https://github.com/w3c/w3c.github.io) - * How to use Git and GitHub at W3C. - * This repository is not exposed through [the Guidebook](https://www.w3.org/guide/). - Note: now that we have a repository for the guidebook, simply add your documentation to it, rather than creating new repositories. diff --git a/editor/resources.md b/editor/resources.md index 97aa3b86b..3179644d7 100644 --- a/editor/resources.md +++ b/editor/resources.md @@ -56,7 +56,7 @@ toc: true ### GitHub * Initial instructions for GitHub beginners: - * [W3C on GitHub](https://w3c.github.io/) + * [W3C on GitHub](../github/) ### For Editor's role diff --git a/github/backup.html b/github/backup.html deleted file mode 100644 index 164ddd634..000000000 --- a/github/backup.html +++ /dev/null @@ -1,49 +0,0 @@ - - - - - - GitHub organizations backups - - - -
-

GitHub organizations backups

-
- - -
-

- W3C relies on Rewind to backup the different GitHub organizations the groups depend on. -

-

- Rewind runs daily backups of all the repositories, including metadata and provides a way to restore a repository if the GitHub support is not able to help. -

-
-

Rewind App (GitHub)

-

- To start the backup process for a GitHub organization, the user w3cbot must be listed as one of the owners of the organization so it can: -

    -
  • install the Rewind App to the organization -
  • import the organization into rewind -
  • restore a repository when needed -
- - After inviting w3cbot, you may request sysreq to add your organization to rewind. -

-
-
- - - diff --git a/github/backup.md b/github/backup.md new file mode 100644 index 000000000..180393463 --- /dev/null +++ b/github/backup.md @@ -0,0 +1,17 @@ +--- +title: GitHub organizations backups +toc: false +--- +W3C relies on [Rewind](https://rewind.com/) to backup the different GitHub organizations the groups depend on. + +Rewind runs daily backups of all the repositories, including metadata and provides a way to restore a repository if the GitHub support is not able to help. + +## Rewind App (GitHub) + +To start the backup process for a GitHub organization, the user [w3cbot](https://github.com/w3cbot) **must** be [listed as one of the owners of the organization](https://knowledge.rewind.com/s/article/which-permissions-do-i-need-to-install-rewind) so it can: + +- Install the [Rewind App](https://github.com/apps/rewind-app-github) to the organization +- Import the organization into Rewind +- Restore a repository when needed + +After inviting w3cbot, you may request [sysreq](mailto:sysreq@w3.org) to add your organization to Rewind. diff --git a/github/best-practices.html b/github/best-practices.html deleted file mode 100644 index da19abfc0..000000000 --- a/github/best-practices.html +++ /dev/null @@ -1,300 +0,0 @@ - - - - - - - - Best practices and recommended tools - - - - - - -
-

Best practices and recommended tools

-
- - - - - -
-
-

For all GitHub users 🔗

-
-

Enable two-factor authentication (2FA) 🔗

-

Two-factor authentication, or 2FA, is an extra layer of - security used when logging into websites or apps to protect your online identity. With 2FA, you have to log in with your username and - password and provide another form of authentication that only you know or have access to. - We encourage all users to enable 2FA in as many services and applications as they use - for which this feature is available — starting with GitHub.

-

You can set it up here: github.com/settings/security.

-
-
-

Own your code 🔗

-

The repositories you contribute to should ideally have a file - .github/CODEOWNERS. - If that is so, suggest to the maintainer edits to that file so that you will be automatically assigned PR reviews for those PR's that - will affect the areas or files that you “own” (ie, that you are usually responsible for).

-

(If that file is missing, point the maintainer of the repository to these two sections: - § settings and § GitHub boilerplate files.)

-
-
-

Submit atomic PR's 🔗

-

Your PR's should tend to be small, and contain one bugfix or new feature only.

-
-
-

Make sure you receive notifications 🔗

-

It is recommended that all users automatically subscribe to - notifications from new W3C repositories. - If/when a new repository is of no interest to them, the user can easily unsubscribe from it.

-

The “danger” of missing important notifications if one does not subscribe to all of them is higher than the slight annoyance - of having to manually unsubscribe from (most) new repositories every time.

-

Users can choose whether to receive those notifications via e-mail, as alerts on the web UI of GH, or in both ways at the same time.

-

Set up automatic watching of new repositories here: - github.com/settings/notifications. - If you receive too much noise, prune the list of repositories that you watch here: - github.com/watching.

-

Repository maintainers should always watch their repositories and respond to changes, issues, PRs, etc.

-
-
-

Delete your branches soon 🔗

-

Branches you create to submit PRs should be deleted as soon as the PR is resolved (either merged or closed for other reasons). - Make a point of deleting a branch when you see its corresponding PR has been merged.

-

To remove old branches from your clone of the repo, run this Git command from time to time:

- 
$ git remote prune origin
-
-
-
-

For project maintainers 🔗

-
-

Set up the repository well 🔗

-
-

Set common settings 🔗

-

Review https://github.com/w3c/<REPO>/settings:

-
    -
  • Does your project use wikis or projects? If not, disabling those options will reduce some - cognitive load, un-clutter the web UI, and prevent absent-minded collaborators from contributing wiki pages or other stuff that - nobody is using nor paying attention to.
    • -
  • Set up GitHub Pages if necessary; select the right branch for that.
    • -
  • In https://github.com/w3c/<REPO>/settings/branches: - -
    • -
  • In https://github.com/w3c/<REPO>/settings/installations, under Services, you may want to add a handy - service; like an IRC notifier, or a Twitter bridge (depending on the nature of your repository, of course).
    • -
-
-
-

Fill in common fields 🔗

-

In particular, the three fields that appear at the top of the main page of the repo: description (something short), - website (often pointing to GitHub Pages) and topics (tags).

-

Check out how those are set up in Echidna, for example.

-
-
-
-

Include sufficient metadata 🔗

-
-

Git special files 🔗

-

Have a .gitignore - (hidden file) in the root directory of your repo to list files and directories that you do not want to keep under version - control. - Typically something along the lines of:

- 
node_modules/
-npm-debug.log
-logs/
-

See an example.

-

Ideally, this file should not contain filenames or patterns that are associated to specific OS's, IDE's or - editors; eg .DS_Store (MacOS), Thumbs.db (Windows), *~ (emacs). - The other contributors don't need to know about the different types of droppings your tools produce, and there are cleaner ways to - ignore files locally, like - configuring your Git to do so.

-
-
-

GitHub boilerplate files 🔗

-

To keep the root directory of the repository clean and manageable, store as many metadata files under .github/ as - possible. - You should certainly have a README.md there.

-

Other useful files you may want to keep under that directory are these (in decreasing order of importance):

- -

An exception to this rule is the file - LICENSE.md, - which should be in the root directory of the project, - or else GitHub will not find it.

-

See an example.

-
-
-

W3C-specific metadata 🔗

-

Usually applicable only to repositories containing specs (not software).

-

See the w3c.json file.

-
-
-
-

Handle permissions well 🔗

-

Make sure you list the right teams and individuals under “Collaborators & teams”:

- 
https://github.com/w3c/<REPO>/settings/collaboration
-

In particular, be conservative about assigning editing (write) permissions and do so only for known collaborators.

-
-
-

Make sure you receive vulnerability alerts 🔗

-

Usually applicable only to repositories containing software (not specs), and assuming the language/platform detected in the - repository is understood and supported by GitHub; find out - in their help pages.

-

Enable vulnerability alerts in settings, here:

- 
https://github.com/w3c/<REPO>/settings#vulnerability-alerts-feature
-

Once enabled, vulnerabilities will be shown highlighted in two places:

-
    -
  • At the top of the main page of the repo; ie https://github.com/w3c/<REPO>
    • -
  • On the Dependency Graph page; ie https://github.com/w3c/<REPO>/network/dependencies
    • -
-

Finally, make sure you are receiving notifications about vulnerability alerts: - github.com/settings/notifications (bottom of the page).

-
-
-

Set up CI 🔗

-

Travis CI is our recommended tool to do CI; check out - our repos there.

-

A particular example of Travis configuration (see links below for more information):

- 
language: node_js
-node_js:                            # ☞ “Building a JavaScript and Node.js project”
-  - "8"
-  - "10"
-before_install:                     # ☞ “Build Stages”
-  - npm install -g npm@latest
-before_script:
-  - cp config.js.example config.js
-script:
-  - npm run build
-after_script:
-  - npm run coveralls
-notifications:                      # ☞ “Configuring Build Notifications”
-  email: false
-  irc:
-    channels:
-      - "irc.w3.org#pub"
-    skip_join: true
-    template:
-      - "%{branch} by %{author} (%{build_url}): %{message}"
-

Travis CI help pages referenced above:

- -

See an example of Travis report page.

-

The specifics of Travis configuration depend greatly on the language/platform and on the dependencies and tools involved. - See the documentation or browse existing repositories using Travis to learn more.

-
-
-

Set up Repository Manager 🔗

-

(Applicable only to repositories containing specs, not software.)

-

You may want to add your new repository containing a spec in - the W3C Repository Manager. - This is a tool that helps with IPR managements from public contributors; check with the Systeam if in doubt.

-
-
-

Patrol branches often 🔗

-

See also Delete your branches soon.

-

From time to time, check the list of all branches in the project, https://github.com/w3c/<REPO>/branches/all, and - delete the ones that aren't being used; branches that are not ahead of the default branch, and branches associated to PRs that - are either merged or closed already, are definitely good candidates for removal. - If in doubt, ask the author of the branch.

-
-
-

Assess the quality of your repo 🔗

-

From time to time, run tools like these to evaluate how well your repositories are maintained, and whether they are outdated or missing - some metadata or files:

- -
-
-
-

See also 🔗

- -
-
- - - - - - diff --git a/github/best-practices.md b/github/best-practices.md new file mode 100644 index 000000000..2e7c19f23 --- /dev/null +++ b/github/best-practices.md @@ -0,0 +1,197 @@ +--- +title: Best practices and recommended tools +toc: true +--- + +## For all GitHub users {#all} + +### Enable two-factor authentication (2FA) {#mfa} + +[Two-factor authentication, or 2FA](https://help.github.com/articles/about-two-factor-authentication/), is an extra layer of security used when logging into websites or apps to protect your online identity. With 2FA, you have to log in with your username and password and provide another form of authentication that only you know or have access to. We encourage all users to enable 2FA in as many services and applications as they use for which this feature is available — starting with GitHub. + +You can set it up here: [`github.com/settings/security`](https://github.com/settings/security). + +### Own your code {#own} + +The repositories you contribute to should ideally have a file [`.github/CODEOWNERS`](https://help.github.com/articles/about-codeowners/). If that is so, suggest to the maintainer edits to that file so that you will be automatically assigned PR reviews for those PR's that will affect the areas or files that you “own” (ie, that you are usually responsible for). + +(If that file is missing, point the maintainer of the repository to these two sections: [*§ settings*](#settings) and [*§ GitHub boilerplate files*](#boilerplate).) + +### Submit atomic PR's {#atomic} + +Your PR's should tend to be small, and contain *one* bugfix or new feature only. + +### Make sure you receive notifications {#notifications} + +It is recommended that all users automatically subscribe to [notifications](https://help.github.com/articles/managing-your-notifications/) from new W3C repositories. If/when a new repository is of no interest to them, the user can easily unsubscribe from it. + +The “danger” of missing important notifications if one does not subscribe to all of them is higher than the slight annoyance of having to manually unsubscribe from (most) new repositories every time. + +Users can choose whether to receive those notifications via e-mail, as alerts on the web UI of GH, or in both ways at the same time. + +Set up automatic watching of new repositories here: [`github.com/settings/notifications`](https://github.com/settings/notifications). If you receive too much noise, prune the list of repositories that you watch here: [`github.com/watching`](https://github.com/watching). + +**Repository maintainers should *always* watch their repositories** and respond to changes, issues, PRs, etc. + +### Delete your branches soon {#branches} + +Branches you create to submit PRs should be deleted as soon as the PR is resolved (either merged or closed for other reasons). Make a point of deleting a branch when you see its corresponding PR has been merged. + +To remove old branches from your clone of the repo, run this Git command from time to time: + +``` +$ git remote prune origin +``` + +## For project maintainers {#maintainers} + +### Set up the repository well {#setup} + +#### Set common settings {#settings} + +Review `https://github.com/w3c//settings`: + +- Does your project use **wikis** or **projects**? If not, disabling those options will reduce some cognitive load, un-clutter the web UI, and prevent absent-minded collaborators from contributing wiki pages or other stuff that nobody is using nor paying attention to. +- Set up **GitHub Pages** if necessary; select the right branch for that. +- In `https://github.com/w3c//settings/branches`: + + - Make sure the **default branch** is `main` or `gh-pages`. + - Consider [enforcing code reviews for PR's](https://help.github.com/articles/enabling-required-reviews-for-pull-requests/), at least for the default branch. +- In `https://github.com/w3c//settings/installations`, under *Services*, you may want to add a handy **service**; like an IRC notifier, or a Twitter bridge (depending on the nature of your repository, of course). + +#### Fill in common fields {#fields} + +In particular, the three fields that appear at the top of the main page of the repo: **description** (something short), **website** (often pointing to GitHub Pages) and **topics** (tags). + +Check out how those are set up [in Echidna](https://github.com/w3c/echidna), for example. + +### Include sufficient metadata {#metadata} + +#### Git special files {#git} + +Have a [`.gitignore`](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring) (hidden file) in the root directory of your repo to list files and directories that you do *not* want to keep under version control. Typically something along the lines of: + +``` +node_modules/ +npm-debug.log +logs/ +``` + +See [an example](https://github.com/w3c/validate-repos/blob/main/.gitignore). + +Ideally, **this file should *not* contain filenames or patterns that are associated to specific OS's, IDE's or editors**; eg `.DS_Store` (MacOS), `Thumbs.db` (Windows), `*~` (emacs). The other contributors don't need to know about the different types of droppings your tools produce, and there are cleaner ways to ignore files *locally*, like [configuring your Git to do so](https://git-scm.com/docs/git-config#Documentation/git-config.txt-coreexcludesFile). + +#### GitHub boilerplate files {#boilerplate} + +To keep the root directory of the repository clean and manageable, store as many metadata files under `.github/` as possible. You should certainly have a [`README.md`](https://help.github.com/articles/about-readmes/) there. + +Other useful files you may want to keep under that directory are these (in decreasing order of importance): + +- [`CONTRIBUTING.md`](https://help.github.com/articles/setting-guidelines-for-repository-contributors/) +- [`ISSUE_TEMPLATE.md` and `PULL_REQUEST_TEMPLATE.md`](https://help.github.com/articles/about-issue-and-pull-request-templates/) +- [`CODEOWNERS`](https://help.github.com/articles/about-codeowners/) +- [`CODE_OF_CONDUCT.md`](https://help.github.com/articles/adding-a-code-of-conduct-to-your-project/) + +An exception to this rule is the file [`LICENSE.md`](https://help.github.com/articles/adding-a-license-to-a-repository/), which should be in the root directory of the project, [or else GitHub will not find it](https://github.com/benbalter/licensee/issues/250#issuecomment-353985847). + +See [an example](https://github.com/w3c/validate-repos/blob/main/LICENSE.md). + +#### W3C-specific metadata {#w3c} + +Usually applicable only to repositories containing specs (*not* software). + +See [the `w3c.json` file](w3c.json.md). + +### Handle permissions well {#perms} + +Make sure you list the right *teams* and *individuals* under “Collaborators & teams”: + +``` +https://github.com/w3c//settings/collaboration +``` + +In particular, be conservative about assigning editing (write) permissions and do so only for known collaborators. + +### Make sure you receive vulnerability alerts {#vulns} + +Usually applicable only to repositories containing software (*not* specs), and assuming the language/platform detected in the repository is understood and supported by GitHub; find out [in their help pages](https://help.github.com/articles/about-security-alerts-for-vulnerable-dependencies/). + +Enable vulnerability alerts in settings, here: + +``` +https://github.com/w3c//settings#vulnerability-alerts-feature +``` + +Once enabled, vulnerabilities will be shown highlighted in two places: + +- At the top of the main page of the repo; ie `https://github.com/w3c/` +- On the *Dependency Graph* page; ie `https://github.com/w3c//network/dependencies` + +Finally, make sure you are receiving *notifications* about vulnerability alerts: [`github.com/settings/notifications`](https://github.com/settings/notifications) (bottom of the page). + +### Set up CI {#ci} + +[Travis CI](https://travis-ci.com/) is our recommended tool to do CI; check out [our repos there](https://travis-ci.org/w3c/). + +A particular example of Travis configuration (see links below for more information): + +```yaml +language: node_js +node_js: # ☞ “Building a JavaScript and Node.js project” + - "8" + - "10" +before_install: # ☞ “Build Stages” + - npm install -g npm@latest +before_script: + - cp config.js.example config.js +script: + - npm run build +after_script: + - npm run coveralls +notifications: # ☞ “Configuring Build Notifications” + email: false + irc: + channels: + - "irc.w3.org#pub" + skip_join: true + template: + - "%{branch} by %{author} (%{build_url}): %{message}" +``` + +Travis CI help pages referenced above: + +- [Building a JavaScript and Node.js project](https://docs.travis-ci.com/user/languages/javascript-with-nodejs/) +- [Build Stages](https://docs.travis-ci.com/user/build-stages/) +- [Configuring Build Notifications](https://docs.travis-ci.com/user/notifications/) + +See [an example of Travis report page](https://travis-ci.org/w3c/echidna). + +The specifics of Travis configuration depend greatly on the language/platform and on the dependencies and tools involved. See [the documentation](https://docs.travis-ci.com/) or browse existing repositories using Travis to learn more. + +### Set up Repository Manager {#repository-manager} + +(Applicable only to repositories containing specs, *not* software.) + +You may want to add your new repository containing a spec in the [W3C Repository Manager](https://labs.w3.org/repo-manager/). This is a tool that helps with IPR managements from public contributors; check with the Systeam if in doubt. + +### Patrol branches often {#branches2} + +See also [Delete your branches soon](#branches). + +From time to time, check the list of all branches in the project, `https://github.com/w3c//branches/all`, and delete the ones that aren't being used; branches that are *not* ahead of the default branch, and branches associated to PRs that are either *merged* or *closed* already, are definitely good candidates for removal. If in doubt, ask the author of the branch. + +### Assess the quality of your repo {#tools} + +From time to time, run tools like these to evaluate how well your repositories are maintained, and whether they are outdated or missing some metadata or files: + +- [`validate-repos`](https://github.com/w3c/validate-repos): a W3C tool, specific for repos containing specs (*not* software); see [the kind of report it produces](https://w3c.github.io/validate-repos/report.html) +- [`forkability`](https://github.com/basicallydan/forkability/): an external project, useful for any kind of public repository with open source + +## See also {#also} + +- GitHub: + - datree: [“Top 10 GitHub Best Practices”](https://www.datree.io/resources/github-best-practices) + - Web Platform Tests: [“Introduction to GitHub”](https://web-platform-tests.org/writing-tests/github-intro.html) + - i18n activity: [“Github guidelines for working with i18n documents”](https://w3c.github.io/i18n-activity/guidelines/github) +- Git: [Git recipes & tricks](git.md) +- Node.js: [best practices, recommended tools and template projects](https://github.com/w3c/nodejs) (public repo). diff --git a/github/faq.html b/github/faq.html deleted file mode 100644 index 590b77f1f..000000000 --- a/github/faq.html +++ /dev/null @@ -1,292 +0,0 @@ - - - - - - FAQ - - - - -
-

FAQ

-
- - - - -
-

- Git is a popular, open-source distributed version control - system, commonly used with GitHub as a convenient central host - of repositories, along with wiki documentation, pull request management and issue tracking. - Several W3C groups are using GitHub infrastructure for specification and test authoring - workflows. Below we include some suggested steps for getting started and answers to some - frequently asked questions about using GitHub for W3C spec work. -

- -
-

Getting started 🔗

- -
-

Informal drafts in your personal account 🔗

-

- Getting started individually obviously doesn't require any approval process. Create an - informal draft (using ReSpec makes it easy) by starting a new repository with your personal - GitHub account. We strongly recommend one repository per document, unless you really - know why you're doing it differently. -

-

- You can just publish HTML as you normally would simply by setting up - GitHub Pages - to use the default branch, main.

-

⚠️ NB: GitHub - Pages can serve content off of one branch and one directory only — if - your repo is hosting different specs, or different versions of the same spec, you will have to - either cram all those documents into that branch/directory (and adapt your workflow around that - file structure) or serve your pages in a different way (eg, setting your own web server or - using some kind of hosting provider).

-
- -
-

Hosting a repository within the w3c organisation 🔗

-

- W3C projects include W3C staff selected projects as well as W3C Working (Interest) Group projects. - It is possible that we decide to assess other group's requests to host a given repository. - In any case, a prerequisite would be identifying the owner(s) either by name or by e-mail address. - Refer to the Guidebook for Community Groups - for more information. -

-
    -
  1. - Your Team Contact should become (if they're not already) a part of the - Owners Team of the W3C - organisation. (Ask any of the current owners directly, or ask on &sysreq. This is only - for W3C Staff.) -
    2. -
  2. - If there is no GitHub team roughly matching the group that will be pushing to that - repository, the Team Contact should create a new team for the editors who will be - contributing to the document, and give that team push and pull access. -
    3. -
  3. - W3C staff (or Team Contacts of the group) create a new repository for each document - (each deliverable, it can of course contain multiple resources). - Add each such repository to the GitHub team so that the contributors - all have push access. Other people can suggest changes by submitting pull requests (in - fact, editors can do that too to enable reviewing before commits, if desired), but not - every contributor will be given direct commit access. -
    4. -
-
- -
-

Detailed steps for staff contacts to create a repo 🔗

-

- - The preferred way to create new repositories is by using - the W3C Repository Manager, in particular this page: - labs.w3.org/repo-manager/repo/new. - -

-

Follow the instructions below only if for some reason you can't use the W3C Repository Manager for this.

-
    -
  1. - Let's say you're working on the unicorn spec. You head to https://github.com/new (which is linked as "New - repository" from the home page). Under Owner you pick "w3c" (which you should have access - to, if not ask someone on IRC) and under repo name you pick "unicorn". Enter a - description, keep it public, initialise with a README, don't pick a .gitignore or a - license. -
    2. -
  2. - If you need to create a new team, go to https://github.com/organizations/w3c/teams/new. - Give the team a name ("Unicorn Editors") and grant them "Push & Pull" (no need for - admin). Save the team. Under "Members", just start typing the user names for the editors, - you'll get a drop down suggesting people. Once you've added them all, under repository - start typing "unicorn" and you should see w3c/unicorn listed. Pick that. -
    3. -
  3. - That will give you a https://github.com/w3c/unicorn with fully configured - access. -
    4. -
-
- -
- -
-

W3C integration 🔗

- -
-

GitHub and W3C mailing lists 🔗

-

- To have notification to the mail list at opening of new bugs/issues and modification of - existing ones from GitHub, you may use the github notification solution - designed by Dominique Hazael-Massieux. -

-
- -
-

Contributor management 🔗

-

- If you wish to accept pull requests from potentially arbitrary contributors but you need to - ensure that they have signed up to the IPR terms, see the - Contributor Management section. -

-
- -
- -
-

Policy 🔗

- -
-

How do we ensure archiving of work done on GitHub? 🔗

-

- As usual, publication of Working Drafts and Recommendations into w3.org/TR/ will be done by - your Group by copying snapshots which satisfy pubrules into the appropriate space, with - W3C-guaranteed archiving. -

-

- Because Git itself decentralises archiving of every change (every user clones all history), - backups of version history of Git repositories are straightforward (since in fact every user - of the repository has a backup). A specific tool to maintain a full backup of the W3C - organisation is being developed, called gh-backup. -

-

- Content that is not part of the repositories themselves (issues, wikis, pull requests, etc.) - are backed up as events to the Pheme system (for - the whole organisation). A Pheme instance is currently - running in beta; and some of the - recent events can be viewed in the Midgard - instance. The full data can be made exploitable as it is all sorted and - indexable. -

-
- -
-

May I use w3.org-hosted CVS or Mercurial instead? 🔗

-

No. Those are old services that are being deprecated.

-
- -
-

What about serving specs using a third-party tool? 🔗

-

It is best to avoid these services and to either keep all documents that need to be displayed as web - pages in the branch that GitHub Pages is serving, set up a proper web server, or use a hosting provider.

-

In the past, some groups used RawGit to serve their HTML - documents with the appropriate MIME type, and from more than one branch (because of - these limitations of GitHub Pages). - That service (RawGit) is now defunct.

-

Nowadays, if you absolutely need such a service, we would probably suggest the following two options -  — with the caveat that it is just a recommendation that comes with no support nor - guarantee, since we do not control these services:

-
    -
  • Staticaly. By default, staticaly's cache is set for - 1 year, except for the files under the main branch. If you need the latest - changes, you may append the following query string ?env=dev to the URL. -
  • raw.githack.com. The UI of this service gives you URLs for - production (1 year cache, no traffic limit) and development (changes reflected within minutes, low-traffic - only) you can use depending on your needs. Note: this service - does warn that excessive traffic to development URLs will be throttled, so use it with caution. -
-

The reason to opt for the services above is that others, like - HTMLPreview, either rely on client-side JavaScript to - generate the page dynamically, are limited to GH repositories only, or alter the pages or the links - within them in some way.

-
- -
-

Will the W3C host an instance of RawGit or a similar service? 🔗

-

No, the Systems Team is not planning to offer a similar service in the foreseeable - future.

-
- -
-

Should we use GitHub for issue management too? 🔗

-

- Issue-management tooling is entirely up to groups to choose. That being said, the same notes - apply as for the previous question: if you wish to communicate with a broader community, - GitHub is usually the better option. -

-
- -
-

How do we manage IPR with specs authored on GitHub? 🔗

-

- In general, in the same way as for any other contribution intake mechanism. GitHub only - tends to be singled out because it often leads to more contributions. -

-

- See Contributor Management for a tool that is available - to automate that process. -

-
- -
-

What shall I do about trolls and spam on GitHub? 🔗

-

- GitHub staff are usually quick to respond to spam or uncivic behaviour on their platform. - When a particular GitHub account is repeatedly causing trouble in a W3C repository, a good - first step is to report the account to GitHub. - To do so, go to that user's profile page (eg, https://github.com/supertroll), - click “Block or report user”, and then “Report abuse”. - If after a while the account is not suspended by GitHub and spam persists, it is possible - to block the account to prevent all interaction with the repository in - the future. - (Write W3C's sysreq if you don't have permissions to - block the account yourself.) -

-
- -
- -
- - - diff --git a/github/faq.md b/github/faq.md new file mode 100644 index 000000000..e90df71f3 --- /dev/null +++ b/github/faq.md @@ -0,0 +1,88 @@ +--- +title: FAQ +toc: true +--- + +[Git](https://git-scm.com/) is a popular, open-source distributed version control system, commonly used with [GitHub](https://github.com/) as a convenient central host of repositories, along with wiki documentation, pull request management and issue tracking. Several W3C groups are using GitHub infrastructure for specification and test authoring workflows. Below we include some suggested steps for getting started and answers to some frequently asked questions about using GitHub for W3C spec work. + +## Getting started {#starting} + +### Informal drafts in your personal account {#drafts} + +Getting started individually obviously doesn't require any approval process. Create an informal draft (using ReSpec makes it easy) by starting a new repository with your personal GitHub account. We strongly recommend one repository per document, unless you really know why you're doing it differently. + +You can just publish HTML as you normally would simply by setting up [GitHub Pages](https://github.com/blog/2228-simpler-github-pages-publishing) to use the default branch, `main`. + +⚠️ **NB:** [GitHub Pages can serve content off of *one branch and one directory only*](https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/) — if your repo is hosting different specs, or different versions of the same spec, you will have to either cram all those documents into that branch/directory (and adapt your workflow around that file structure) or serve your pages in a different way (eg, setting your own web server or [using some kind of hosting provider](#others)). + +### Hosting a repository within the `w3c` organization {#repos} + +W3C projects include W3C staff selected projects as well as W3C Working (Interest) Group projects. It is possible that we decide to assess other group's requests to host a given repository. In any case, a prerequisite would be identifying the owner(s) either by name or by e-mail address. Refer to [the Guidebook for Community Groups](https://www.w3.org/2016/04/cg-support/#what) for more information. + +1. Your Team Contact should become (if they're not already) a part of the [Owners Team](https://github.com/organizations/w3c/settings/owners) of the W3C organization. (Ask any of the current owners directly, or ask on &sysreq. This is only for W3C Staff.) +1. If there is no GitHub team roughly matching the group that will be pushing to that repository, the Team Contact should create a new team for the editors who will be contributing to the document, and give that team push and pull access. +1. W3C staff (or Team Contacts of the group) create a new repository for each document (each deliverable, it can of course contain multiple resources). Add each such repository to the GitHub team so that the contributors all have push access. Other people can suggest changes by submitting pull requests (in fact, editors can do that too to enable reviewing before commits, if desired), but not every contributor will be given direct commit access. + +### Detailed steps for staff contacts to create a repo {#steps} + +**The preferred way to create new repositories is by using the [W3C Repository Manager](https://labs.w3.org/repo-manager/), in particular this page: [`labs.w3.org/repo-manager/repo/new`](https://labs.w3.org/repo-manager/repo/new).** + +Follow the instructions below only if for some reason you can't use the W3C Repository Manager for this. + +1. Let's say you're working on the unicorn spec. You head to [https://github.com/new](https://github.com/new) (which is linked as "New repository" from the home page). Under Owner you pick "w3c" (which you should have access to, if not ask someone on IRC) and under repo name you pick "unicorn". Enter a description, keep it public, initialise with a README, don't pick a .gitignore or a license. +1. If you need to create a new team, go to [https://github.com/organizations/w3c/teams/new](https://github.com/organizations/w3c/teams/new). Give the team a name ("Unicorn Editors") and grant them "Push & Pull" (no need for admin). Save the team. Under "Members", just start typing the user names for the editors, you'll get a drop down suggesting people. Once you've added them all, under repository start typing "unicorn" and you should see w3c/unicorn listed. Pick that. +1. That will give you a `https://github.com/w3c/unicorn` with fully configured access. + +## W3C integration {#integration} + +### GitHub and W3C mailing lists {#mail} + +To have notification to the mail list at opening of new bugs/issues and modification of existing ones from GitHub, you may use the [github notification solution](https://github.com/dontcallmedom/github-notify-ml/) designed by Dominique Hazael-Massieux. + +### Contributor management {#contributors} + +If you wish to accept pull requests from potentially arbitrary contributors but you need to ensure that they have signed up to the IPR terms, see the [Contributor Management](repo-management.md) section. + +## Policy {#policy} + +### How do we ensure archiving of work done on GitHub? {#archiving} + +As usual, publication of Working Drafts and Recommendations into w3.org/TR/ will be done by your Group by copying snapshots which satisfy pubrules into the appropriate space, with W3C-guaranteed archiving. + +Because Git itself decentralises archiving of every change (every user clones all history), backups of version history of Git repositories are straightforward (since in fact every user of the repository has a backup). A specific tool to maintain a full backup of the W3C organization is being developed, called [gh-backup](https://github.com/w3c/gh-backup). + +Content that is not part of the repositories themselves (issues, wikis, pull requests, etc.) are backed up as events to the [Pheme](https://github.com/w3c/pheme) system (for the whole organization). A Pheme instance is currently [running in beta](https://labs.w3.org/pheme/); and some of the recent events can be viewed in the [Midgard instance](https://labs.w3.org/midgard/). The full data can be made exploitable as it is all sorted and indexable. + +### May I use w3.org-hosted CVS or Mercurial instead? {#alternatives} + +No. Those are old services that are being deprecated. + +### What about serving specs using a third-party tool? {#others} + +It is best to avoid these services and to either keep all documents that need to be displayed as web pages in the branch that GitHub Pages is serving, set up a proper web server, or use a hosting provider. + +In the past, some groups used [RawGit](https://rawgit.com/) to serve their HTML documents with the appropriate MIME type, and from more than one branch (because of [these limitations of GitHub Pages](#drafts)). That service (RawGit) is now defunct. + +Nowadays, if you absolutely need such a service, we would probably suggest the following options — with the caveat that *it is just a recommendation that comes with no support nor guarantee*, since we do *not* control these services: + +- [raw.githack.com](https://raw.githack.com/). The UI of this service gives you URLs for production (1 year cache, no traffic limit) and development (changes reflected within minutes, low-traffic only) you can use depending on your needs. **Note**: this service does warn that excessive traffic to development URLs will be throttled, so use it with caution. + +The reason to opt for the services above is that others, like [HTMLPreview](https://htmlpreview.github.io/), either rely on client-side JavaScript to generate the page dynamically, are limited to GH repositories only, or alter the pages or the links within them in some way. + +### Will the W3C host an instance of RawGit or a similar service? {#host} + +No, the Systems Team is *not* planning to offer a similar service in the foreseeable future. + +### Should we use GitHub for issue management too? {#issues} + +Issue-management tooling is entirely up to groups to choose. That being said, the same notes apply as for the previous question: if you wish to communicate with a broader community, GitHub is usually the better option. + +### How do we manage IPR with specs authored on GitHub? {#ipr} + +In general, in the same way as for any other contribution intake mechanism. GitHub only tends to be singled out because it often leads to more contributions. + +See [Contributor Management](repo-management.md) for a tool that is available to automate that process. + +### What shall I do about trolls and spam on GitHub? {#trolls} + +GitHub staff are usually quick to respond to spam or uncivic behaviour on their platform. When a particular GitHub account is repeatedly causing trouble in a W3C repository, a good first step is to **report the account** to GitHub. To do so, go to that user's profile page (eg, `https://github.com/supertroll`), click “Block or report user”, and then “Report abuse”. If after a while the account is not suspended by GitHub and spam persists, it is possible to **block the account** to prevent all interaction with the repository in the future. ([Write W3C's sysreq](mailto:sysreq@w3.org) if you don't have permissions to block the account yourself.) diff --git a/github/git.html b/github/git.html deleted file mode 100644 index 76fc2fbcd..000000000 --- a/github/git.html +++ /dev/null @@ -1,127 +0,0 @@ - - - - - - - - Git recipes & tricks - - - - - - -
-

Git recipes & tricks

-
- - - - - -
-

These are some low-level tips for the console, for power users of Git.

-
-

Useful config 🔗

-
    -
  • branch.autosetuprebase=always - (documentation): - I find it easier to work with Git this way
    • -
  • core.editor=emacs -nw - (documentation): - that's the editor that will be invoked every time Git needs to ask you about a commit message, when you're squashing commits, etc - (and of course, you want emacs for that)
    • -
  • commit.gpgsign=true - (documentation) - and gpg.program=gpg2 - (documentation): - you will need to set up these variables (and possibly a couple other) if you want to - sign your commits to GitHub using GPG (recommended)
    • -
-
-
-

Safest way to “update” a local copy 🔗

-

I find this sequence of commands the “safest” way to quickly “refresh” a clone of some remote repo, and at the same time check its status - (where “safest” means “reducing to the minimum the probability of messing up things with conflicts, outdated branches, uncommitted - changes, etc”):

- 
$ git branch -a
-$ git pull -r
-$ git status
-$ git remote prune origin --dry
-
  • $ git branch -a displays information about all branches, both local and remote
    • -
  • $ git pull -r fetches changes from the remote and - “rebases the current branch on top of the upstream branch after fetching” -
    • -
  • $ git status shows you the status of your copy: whether there are new files, missing files, unstaged changes, or commits - pending push
    • -
  • $ git remote prune origin --dry tells you if any branch in the remote has been recently removed. - (Submit the same command without the --dry part to actually remove those remotes from your local - origin. - That will still not remove local branches automatically, but you can do that yourself with - git branch -d <BRANCH> if you see some branch is no longer necessary.) -
    • -
-

You can have those four lines as an alias, or inside a script somewhere.

-

Even better: if you set up the aliases suggested above, the whole thing becomes:

- 
$ git br -a;git pl -r;git st;git re prune origin --dry
-

You can then type it and run it just once, and, from that moment on, simply recover the line from your shell history.

-

For example, if you're using Bash: press Ctrl+r, then start typing a distinctive chunk of the line - (eg, r;, or st;gi); if you used it not too long ago for the last time, the entire line should appear, and you can - simply press Enter.

-
-
-

An alias to view the history of the repo 🔗

- 
alias.lg=log --graph --abbrev-commit --decorate --date=relative \
---format=format:'%C(bold blue)%h%C(reset)          \
-- %C(bold green)(%ar)%C(reset) %C(white)%s%C(reset) \
-%C(dim white)- %an%C(reset)%C(bold yellow)%d%C(reset)' --all
-

Then, simply type

- 
$ git lg
-

for a colourful graph of commits, tags and branches.

-
-
-

See also 🔗

- -
-
- - - - - - diff --git a/github/git.md b/github/git.md new file mode 100644 index 000000000..73272e992 --- /dev/null +++ b/github/git.md @@ -0,0 +1,67 @@ +--- +title: Git recipes & tricks +toc: true +--- + +These are some **low-level tips for the console**, for *power users* of Git. + +## Useful config {#config} + +- `branch.autosetuprebase=always` ([documentation](https://git-scm.com/docs/git-config#git-config-branchautoSetupRebase)): I find it easier to work with Git this way +- `core.editor=emacs -nw` ([documentation](https://git-scm.com/docs/git-config#git-config-coreeditor)): that's the editor that will be invoked every time Git needs to ask you about a commit message, when you're squashing commits, etc (and of course, you want emacs for that) +- `commit.gpgsign=true` ([documentation](https://git-scm.com/docs/git-config#git-config-commitgpgSign)) and `gpg.program=gpg2` ([documentation](https://git-scm.com/docs/git-config#git-config-gpgprogram)): you will need to set up these variables (and possibly a couple other) if you want to [sign your commits to GitHub using GPG (recommended)](https://help.github.com/articles/signing-commits-with-gpg/) + +## Safest way to “update” a local copy {#update} + +I find this sequence of commands the “safest” way to quickly “refresh” a clone of some remote repo, and at the same time check its status (where “safest” means *“reducing to the minimum the probability of messing up things with conflicts, outdated branches, uncommitted changes, etc”*): + +```shell +$ git branch -a +$ git pull -r +$ git status +$ git remote prune origin --dry +``` + +- `git branch -a` displays information about *all* branches, both local and *remote* +- `git pull -r` fetches changes from the *remote* and [“rebases the current branch on top of the upstream branch after fetching”](https://git-scm.com/docs/git-pull#git-pull--r) +- `git status` shows you the status of your copy: whether there are new files, missing files, unstaged changes, or commits pending push +- `git remote prune origin --dry` tells you if any branch in the *remote* has been recently removed. (Submit the same command *without* the `--dry` part to actually remove those remotes from your local `origin`. That will still *not* remove local branches automatically, but you can do that yourself with `git branch -d ` if you see some branch is no longer necessary.) + +You can have those four lines as an *alias*, or inside a *script* somewhere. + +Even better: if you set up [the aliases suggested above](#aliases), the whole thing becomes: + +```shell +$ git br -a;git pl -r;git st;git re prune origin --dry +``` + +You can then type it and run it just once, and, from that moment on, simply recover the line from your shell history. + +For example, if you're using Bash: press `Ctrl`+`r`, then start typing a distinctive chunk of the line (eg, `r;`, or `st;gi`); if you used it not too long ago for the last time, the entire line should appear, and you can simply press `Enter`. + +## An alias to view the history of the repo {#lg} + +```shell +alias.lg=log --graph --abbrev-commit --decorate --date=relative \ +--format=format:'%C(bold blue)%h%C(reset) \ +- %C(bold green)(%ar)%C(reset) %C(white)%s%C(reset) \ +%C(dim white)- %an%C(reset)%C(bold yellow)%d%C(reset)' --all +``` + +Then, simply type + +```shell +$ git lg +``` + +for a colourful graph of commits, tags and branches. + +## See also {#also} + +- Git: + + - [Official Git reference](https://git-scm.com/docs) + - [*The* Git book online](https://git-scm.com/book/en/v2) + - CSS WG wiki: [“Quick Guide to Using Git”](https://wiki.csswg.org/tools/git) + - Out there: [“Flight rules for Git”](https://github.com/k88hudson/git-flight-rules) +- GitHub: [best practices and recommended tools](best-practices.md) diff --git a/github/index.html b/github/index.html deleted file mode 100644 index ab09a65aa..000000000 --- a/github/index.html +++ /dev/null @@ -1,122 +0,0 @@ - - - - - - W3C on GitHub - - - - -
-

W3C on GitHub

-
- - -
-

- Many W3C work groups conduct their work in Github, but not all. Please, explore our repos, watch, star, contribute. -

-

- The purpose of this page is to progressively list the resources useful when working on - W3C projects using GitHub. - The following links should help you find your way. - Refer to the FAQ for details about the breadth and scope of W3C projects. -

-
-
Repositories
-
- If you are looking for a specific project that we maintain on GitHub, the best is to go - straight to the list of repositories, which is searchable.
- Repositories under the W3C organization may represent the work of Working Groups, Interest Groups, - Community Groups, or Team projects, with varied status and formality. Documents and repositories should - maintain their own status indicators. - -
-
Best practices and recommended tools
-
- General guidelines, useful tools, tips. -
-
Git recipes & tricks
-
- Configuration, useful aliases and advice — specific for command-line Git. -
-
GitHub Help
-
- Most of the issues people have using GitHub are in fact due to git. General - git and GitHub questions will not be addressed here. - GitHub's own help site linked above is a very helpful resource. - You can also usually just cut and paste from - Stack Overflow's git questions. - Eric Eggert conducted a training - session about Git and GitHub (1h40′ video + slides). -
-
FAQ
-
- Introductory-level questions that are commonly asked about using GitHub specifically in a W3C - context. -
-
Using GitHub for Spec Work
-
- A step-by-step guide to get up and running with a specification on GitHub, from Tobie. -
-
Transfer a repository to the W3C GitHub organization
-
- A guide to transfer a GitHub repository to the W3C organization. -
-
Workflow for editors and other contributors
-
- A guide for a clean and sane workflow for editors. -
-
Contributor Management
-
- If your group accepts contributions from a broad set of people through pull requests, this - tool can help you make sure that the contributors have signed the requisite IPR agreements. -
-
- Automatic - Publication from GitHub -
-
- In general, it is strongly recommended to use Echidna to publish TR documents rather than the - manual path that goes through the Webmaster (assuming of course that your document is of a - supported type). This document explains how to set up your repository using Travis CI in order - to automatically publish on every commit (to a given branch) and never again have to worry - about what people used to call “heartbeat” publications. With this, you can even get rid of - the notion of Editor's Draft altogether. -
-
Keeping Track with Midgard
-
- Because work that happens on GitHub is spread out across many repositories, it can be challenging - to remain informed about what's going on. Midgard helps there by - filtering the data into mailboxes so that you can for instance get all the events for - WebRTC repositories. Log in there with your W3C credentials, and just start using it. Note: - it does not at this time have many filters and it is likely that your area of interest may not - yet have one. If you wish to add one (which is easy) you should read - the - documentation on Pheme filters. -
-
The w3c.json file
-
- This is a small metadata file that is recommended for GitHub repositories under the - w3c organisation. -
-
Backup of GitHub organizations
-
How W3C keeps a backup of the different GitHub organizations
-
-
- - - diff --git a/github/index.md b/github/index.md new file mode 100644 index 000000000..db6402059 --- /dev/null +++ b/github/index.md @@ -0,0 +1,47 @@ +--- +title: W3C on GitHub +toc: false +--- +Many W3C work groups conduct their work in Github, but not all. Please, explore our repos, watch, star, contribute. + +The purpose of this page is to progressively list the resources useful when working on W3C projects using GitHub. The following links should help you find your way. Refer to the [FAQ](faq.md) for details about the breadth and scope of W3C projects. + +[Repositories](https://github.com/w3c/) +: If you are looking for a specific project that we maintain on GitHub, the best is to go straight to the list of repositories, which is searchable. +Repositories under the W3C organization may represent the work of Working Groups, Interest Groups, Community Groups, or Team projects, with varied status and formality. Documents and repositories should maintain their own status indicators. + +[Best practices and recommended tools](best-practices.md) +: General guidelines, useful tools, tips. + +[Git recipes & tricks](git.md) +: Configuration, useful aliases and advice — specific for command-line Git. + +[GitHub Help](https://help.github.com/) +: Most of the issues people have using GitHub are in fact due to `git`. General `git` and GitHub questions will not be addressed here. GitHub's own help site linked above is a very helpful resource. You can also usually just cut and paste from [Stack Overflow's git questions](http://stackoverflow.com/questions/tagged/git). Eric Eggert conducted a [training session about Git and GitHub (1h40′ video + slides)](http://w3c.github.io/wai-gh-training-2015-06-29/). + +[FAQ](faq.md) +: Introductory-level questions that are commonly asked about using GitHub specifically in a W3C context. + +[Using GitHub for Spec Work](specs.md) +: A step-by-step guide to get up and running with a specification on GitHub, from Tobie. + +[Transfer a repository to the W3C GitHub organization](repo-transfer.md) +: A guide to transfer a GitHub repository to the W3C organization. + +[Workflow for editors and other contributors](workflow.md) +: A guide for a clean and sane workflow for editors. + +[Contributor Management](repo-management.md) +: If your group accepts contributions from a broad set of people through pull requests, this tool can help you make sure that the contributors have signed the requisite IPR agreements. + +[Automatic Publication from GitHub](https://github.com/w3c/echidna/wiki/Setting-up-Echidna-as-a-GitHub-hook) +: In general, it is strongly recommended to use [Echidna](https://github.com/w3c/echidna/wiki) to publish TR documents rather than the manual path that goes through the Webmaster (assuming of course that your document is of a supported type). This document explains how to set up your repository using Travis CI in order to automatically publish on every commit (to a given branch) and never again have to worry about what people used to call “heartbeat” publications. With this, you can even get rid of the notion of Editor's Draft altogether. + +[Keeping Track with Midgard](https://labs.w3.org/midgard/) +: Because work that happens on GitHub is spread out across many repositories, it can be challenging to remain informed about what's going on. Midgard helps there by filtering the data into mailboxes so that you can for instance get all the events for WebRTC repositories. Log in there with your W3C credentials, and just start using it. Note: it does not at this time have many filters and it is likely that your area of interest may not yet have one. If you wish to add one (which is easy) you should read [the documentation on Pheme filters](https://github.com/w3c/midgard/blob/master/DEVELOPMENT.md#libfilterseventsjs). + +[The `w3c.json` file](w3c.json.md) +: This is a small metadata file that is recommended for GitHub repositories under the `w3c` organization. + +[Backup of GitHub organizations](backup.md) +: How W3C keeps a backup of the different GitHub organizations. diff --git a/github/issue-metadata.html b/github/issue-metadata.html deleted file mode 100644 index 204dbe44b..000000000 --- a/github/issue-metadata.html +++ /dev/null @@ -1,248 +0,0 @@ - - - - - - Labels and Other Metadata for Issues and Pull Requests - - - - - -
-

Labels and Other Metadata for Issues and Pull Requests

-
- - -
-

- This page describes how to use GitHub labels, milestones, and projects in a uniform way across W3C specifications. -

- -
-

Labels

- Labels describe the kind of issue or specific work that's needed to advance an issue. - -
-

Horizontal labels

-

- Those labels are there to facilitate horizontal reviews. -

-
-
security
-
Affects the degree of resistance to, or protection from, harm of Web technologies.
-
privacy
-
-

- Affects the collection, processing and publication of personal data in Web technologies. -

-
-
Accessibility
-
-

Affects the design of Web technologies for people with disabilities.

-
-
Internationalization
-
-

Affects the adaptation of Web technologies to different languages or regional differences.

-
-
architecture
-
Affects the underlying principles that should be adhered to by all Web technologies.
-
performance
-
Affects the download and display speed of Web technologies.
-
device independence
-
Affects the ability of Web technologies to function on a wide variety of devices.
-
-
-
-

Testing and Implementations

-

Those labels are meant to track testing and implementation status.

-
-
-
-
-
-
-
-

Specifications

-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-

Milestones

- Milestones describe the scheduling of bug fixes and changes. - Often an issue is labeled with a particular milestone as a way to postpone work on it until after work needed for an earlier milestone. - -
-
experiment
-
Resolve before experimenting with the new feature on general users.
-
migrate
-
Resolve before migrating the spec from the WICG to a Working Group.
-
FPWD
-
Resolve before creating a First Public Working Draft.
-
CR
-
Resolve before advancing the spec to Candidate Recommendation.
-
PR
-
Resolve before advancing the spec to Proposed Recommendation.
-
REC
-
Resolve before advancing the spec to Recommendation.
-
level-2
-
Work on these issues after the level-1 spec is complete.
-
future-work
-
Work on these issues at an unspecified time in the future.
-
-
-
-

Wide Review

-

1-The WG processes the comment, and provides a resolution.

- -
-
WR-open
-
Comment received, not yet processed by the WG
-
WR-pending
-
Discussed but pending WG resolution
-
WR-resolved
-
WG resolution, (approved by WG)
-
WR-spec-updated
-
WG resolution and spec updated
-
WR-resolved-partial
-
Partial WG resolution (partially approved by WG)
-
WR-spec-updated-partial
-
Partial WG resolution and spec updated
-
WR-rejected
-
Comment Rejected by WG
-
- -

For each comment, please fill a "type" with above labels

- -

2-Once the WG has processed all comments, the next steps are to get approval from the commenter

-
WR-response-drafted
-
Response to commenter drafted by WG
-
WR-response-sent
-
Response send to commenter
-
WR-commenter-rejected
-
Response rejected by commenter
-
WR-commenter-agreed
-
Response agreed by commenter
-
WR-commenter-agreed-partial
-
Response partially agreed by commenter (needs more discussion)
-
WR-commenter-no-response
-
No Response received from commenter within the stated period
- - -

For more information please refer to the TTWG wiki Wide Review page

. - -

Note that groups may work on a level-2 spec concurrently with pushing the - level-1 spec through the Recommendation process, so repositories may need - milestones like "level-2-CR".

-
-
-

Projects

- Projects describe separate features within a larger specification. - Usually, prefer to create a new repository to track greenfield feature development, and take it through the incubation process instead of using a project within an existing spec repository. - Even when used, project names are generally not shared between specifications, so we don't list samples here. -
-
- - - - diff --git a/github/issue-metadata.md b/github/issue-metadata.md new file mode 100644 index 000000000..2e6cef25a --- /dev/null +++ b/github/issue-metadata.md @@ -0,0 +1,225 @@ +--- +title: Labels and Other Metadata for Issues and Pull Requests +toc: true +--- + +This page describes how to use GitHub [labels](#labels), [milestones](#milestones), and [projects](#projects) in a uniform way across W3C specifications. + +## Labels {#labels} + +[Labels](https://help.github.com/articles/creating-and-editing-labels-for-issues-and-pull-requests/) describe the kind of issue or specific work that's needed to advance an issue. + +### Horizontal Reviews {#horizontal-reviews} + +Those labels are there to facilitate horizontal reviews. + +
+
Security
+
+

+ Affects the degree of resistance to, or protection from, harm of Web technologies. +

+
+
Privacy
+
+

+ Affects the collection, processing and publication of personal data in Web technologies. +

+
+
Accessibility
+
+

Affects the design of Web technologies for people with disabilities.

+
+
Internationalization
+
+

Affects the adaptation of Web technologies to different languages or regional differences.

+
+
Architecture
+
Affects the underlying principles that should be adhered to by all Web technologies.
+
Performance
+
Affects the download and display speed of Web technologies.
+
device independence
+
Affects the ability of Web technologies to function on a wide variety of devices.
+
+ +### Testing and Implementations {#testing} + +Those labels are meant to track testing and implementation status. + +
+
+
+
+
+ +### Specifications {#specifications} + +
+
+
+
+
+
+
+
+
+
+
+
+
+ +## Milestones {#milestones} + +[Milestones](https://help.github.com/articles/tracking-the-progress-of-your-work-with-milestones/) describe the scheduling of bug fixes and changes. Often an issue is labeled with a particular milestone as a way to postpone work on it until after work needed for an earlier milestone. + +experiment +: Resolve before experimenting with the new feature on general users. + +migrate +: Resolve before [migrating](https://wicg.github.io/admin/intent-to-migrate.html) the spec from the [WICG](https://www.w3.org/community/wicg/) to a Working Group. + +FPWD +: Resolve before creating a [First Public Working Draft](https://www.w3.org/policies/process/#first-wd). + +CR +: Resolve before advancing the spec to [Candidate Recommendation](https://www.w3.org/policies/process/#candidate-rec). + +PR +: Resolve before advancing the spec to [Proposed Recommendation](https://www.w3.org/policies/process/#rec-pr). + +REC +: Resolve before advancing the spec to [Recommendation](https://www.w3.org/policies/process/#rec-publication). + +level-2 +: Work on these issues after the level-1 spec is complete. + +future-work +: Work on these issues at an unspecified time in the future. + +## Wide Review {#wide-review} + +1- The WG processes the comment, and provides a resolution. + +WR-open +: Comment received, not yet processed by the WG + +WR-pending +: Discussed but pending WG resolution + +WR-resolved +: WG resolution, (approved by WG) + +WR-spec-updated +: WG resolution and spec updated + +WR-resolved-partial +: Partial WG resolution (partially approved by WG) + +WR-spec-updated-partial +: Partial WG resolution and spec updated + +WR-rejected +: Comment Rejected by WG + +For each comment, please fill a "type" [with above labels](#type) + +2- Once the WG has processed all comments, the next steps are to get approval from the commenter + +WR-response-drafted +: Response to commenter drafted by WG + +WR-response-sent +: Response send to commenter + +WR-commenter-rejected +: Response rejected by commenter + +WR-commenter-agreed +: Response agreed by commenter + +WR-commenter-agreed-partial +: Response partially agreed by commenter (needs more discussion) + +WR-commenter-no-response +: No Response received from commenter within the stated period + +For more information please refer to the [TTWG wiki Wide Review page](https://www.w3.org/wiki/TimedText/TTML2_Wide_Review). + +Note that groups may work on a level-2 spec concurrently with pushing the level-1 spec through the Recommendation process, so repositories may need milestones like "level-2-CR". + +## Projects {#projects} + +[Projects](https://help.github.com/articles/tracking-the-progress-of-your-work-with-project-boards/) describe separate features within a larger specification. Usually, prefer to create a new repository to track greenfield feature development, and take it through the [incubation process](https://www.w3.org/blog/2015/wicg/) instead of using a project within an existing spec repository. Even when used, project names are generally not shared between specifications, so we don't list samples here. + + + + diff --git a/github/repo-management.html b/github/repo-management.html deleted file mode 100644 index 238fda189..000000000 --- a/github/repo-management.html +++ /dev/null @@ -1,195 +0,0 @@ - - - - - - Contributor Management - - - - -
-

Contributor Management

-
- - -
-

- This document covers a tool that was created to support contributions made to a group, under the - form of pull requests, in order to assess whether they are IPR-OK or not. -

-

- The tool is at: - https://labs.w3.org/repo-manager/. -

-

- A number of operations in the tool require logging in through GitHub as the related actions you can undertake through the tool (or that the tool can - undertake on your behalf when reacting to a GitHub event) require authorized access to GitHub. -

-

- There are several tools of use: -

-
-

New Repository login required

-

- This is basically what people should use when they want to start a new specification in a CG or a WG. It gives you a choice of the organisations under which you are allowed to create a new - repo (including your own user), and you can pick the name of the repo and the group(s) to - which it belongs. -

-

- Hitting "Create" can take a little while as the tool does all of the following, live: -

-
    -
  • - Creates the repo on GitHub -
    • -
  • - Adds several files, notably the LICENSE and CONTRIBUTE.md, a - w3c.json file which can be used by other tools, and an index.html - that's a bare-bones ReSpec spec ready to be edited. -
    • -
  • - Adds a hook to the repo such that pull requests and comments on them are sent to us, - including one distinct cryptographic secret per repo. -
    • -
  • - Saves all the relevant info on our side. -
    • -
-

- Most users should only ever have to use that. Once done they can go and play in their repo. -

-
-
-

Import Repository login required

-

- This is the same as "New" but for an existing repo. It will *never* overwrite something there - so it is the user's responsibility to check that the repo is okay. -

-
-
-

How Pull Requests Get Handled

-

- Whenever a pull request is made against a repo that is under the tool's management,the tool gets - notified. It uses this information to assess if the PR is acceptable (i.e. all its - contributors have made the relevant IPR commitment). -

-

- Count as contributors not just the person making the pull request, but also anyone added - either in the PR description or in any subsequent comment using "+@username" on a line on its - own. If a contributor was added by mistake, she can be removed wit "-@username" on a line on - its own. -

-

- Every time a PR is created or has a comment with a username change, the status of the PR is - changed. If it's okay it'll get changed to green with a note indicating that it's fine; if not - it gets changed to some ugly brown with a red cross (and a link that people can use to check - the issue in more detail). -

-

On the page that explains the IPR failure, one can mark a given Pull Request as non-substantive: this will post a comment on the pull request under the name of the user, and will clear the flag for the said pull request.

- -

When a pull request gets flagged as not OK by the tool, it will attempt to notify the github users listed in the contacts property of the w3c.json file in the repo.

- -

When it gets flagged as not OK because the contributor could not be automatically associated with a W3C profile, the contributor will also be notified to ask them to connect their W3C & GitHub accounts. - -

-
-

Currently Open Pull Requests

-

- This list all PRs that are now open, even old ones. It lists useful details such as which - users are being problematic either because they are unknown (not in the system at all) or - outside (known to the system but not in one of the right groups for that repo). -

-

- You can go to PR details by clicking "Details". -

-
-
-

PR Details

-

- If the PR is not in an acceptable state, this will list problematic users with possible options to fix - each of them, and a button to "Mark the PR as non-substantive".

-

- The vast majority of non-acceptable PRs for a newly added repo will come from people whose W3C profile is not known (and thus neither are their affiliation and associated IPR commitments). -

-

- When all problematic users have had their W3C profile associated, return to the PR details page and hit - "Revalidate". We hope in the future to revalidate every time a user is added or edited. Revalidation will of course update both the local - state and the PR's mergability indicator on GitHub. -

-
-
-

Active Last Week PRs

-

- This is a list of pull requests, in any state, that saw activity last week. They can be - filtered according to the affiliation of the companies that made the contributions. This is - essentially so that AC reps who have people in CGs who are only supposed to contribute to some - specific work but not all of it can monitor what's been going on and avail themselves of their - 45 days retraction window. Similar affordances are available as for the list of open PRs. -

-
-
-

Edit User login required

-

In most cases, this interface will not be needed - it is only useful for cases where it is not possible or practical for a GitHub user to associate their GitHub account with their W3C account.

- -

- The interface to edit users is where the W3C data model and the GitHub data model get to meet. - This alone is scary; I've tried to make it less scary. -

-

- A list of the groups known to the system is show, the user can be added and removed from them - there. If the user's affiliation is unset, once some groups have been added you can click - "Set". This will load up a list that is the *intersection* of membership in the selected - groups. The UI will also try to select the user with the name matching their GitHub profile - (which may not always work, but often does). Hitting "OK" will associate the GH user with the - W3C user, making it possible for us to use affiliation information. Don't forget to hit - "Save". -

-
-
-

Admin > Users admin required

-

- This is a list of users. Things you can do there include making them admins and giving them - blanket contribution rights. USE EITHER WITH CARE. -

-

- Admins should normally not be able to break the system, but they can enter all sorts of bogus - information that would be really annoying. Only grant admin when you're sure; it's probably - better to ask others first. -

-

- Blanket is a different type of superpower: users with blanket access are considered acceptable - contributors to ALL repos, irrespective of their group memberships. This should normally be - restricted to W3C team people. -

-
-
-

Admin > Groups admin required

-

- This is a list of all W3C groups. You will note that most have an "Add" button next to them: - those are the ones that are in W3C but not in this system. Please do *not* start adding groups - unless they explicitly want to be managed under this system. We only want people to - create/import repos for groups that are actually using this system. Clicking "Add" makes that - group one of those available for repos and users to belong to. -

-

- The source is at https://github.com/w3c/ash-nazg. -

-
-
- - - diff --git a/github/repo-management.md b/github/repo-management.md new file mode 100644 index 000000000..36ba7181f --- /dev/null +++ b/github/repo-management.md @@ -0,0 +1,93 @@ +--- +title: Contributor Management +toc: true +--- + +This document covers a tool that was created to support contributions made to a group, under the form of pull requests, in order to assess whether they are IPR-OK or not. + +The tool is at: [https://labs.w3.org/repo-manager/](https://labs.w3.org/repo-manager/). + +A number of operations in the tool require logging in through GitHub as the related actions you can undertake through the tool (or that the tool can undertake on your behalf when reacting to a GitHub event) require authorized access to GitHub. + +There are several tools of use: + +## New Repository + +**Login required** + +This is basically what people should use when they want to start a new specification in a CG or a WG. It gives you a choice of the organizations under which you are allowed to create a new repo (including your own user), and you can pick the name of the repo and the group(s) to which it belongs. + +Hitting "Create" can take a little while as the tool does all of the following, live: + +- Creates the repo on GitHub +- Adds several files, notably the `LICENSE` and `CONTRIBUTE.md`, a [`w3c.json`](w3c.json.md) file which can be used by other tools, and an `index.html` that's a bare-bones ReSpec spec ready to be edited. +- Adds a hook to the repo such that pull requests and comments on them are sent to us, including one distinct cryptographic secret per repo. +- Saves all the relevant info on our side. + +Most users should only ever have to use that. Once done they can go and play in their repo. + +## Import Repository + +**Login required** + +This is the same as "New" but for an existing repo. It will **never** overwrite something there so it is the user's responsibility to check that the repo is okay. + +## How Pull Requests Get Handled + +Whenever a pull request is made against a repo that is under the tool's management,the tool gets notified. It uses this information to assess if the PR is acceptable (i.e. all its contributors have made the relevant IPR commitment). + +Count as contributors not just the person making the pull request, but also anyone added either in the PR description or in any subsequent comment using "`+@username`" on a line on its own. If a contributor was added by mistake, they can be removed with "`-@username`" on a line on its own. + +Every time a PR is created or has a comment with a username change, the status of the PR is changed. If it's okay it'll get changed to green with a note indicating that it's fine; if not it gets changed to some ugly brown with a red cross (and a link that people can use to check the issue in more detail). + +On the page that explains the IPR failure, one can mark a given Pull Request as non-[substantive](https://www.w3.org/policies/process/#substantive-change): this will post a comment on the pull request under the name of the user, and will clear the flag for the said pull request. + +When a pull request gets flagged as not OK by the tool, it will attempt to notify the GitHub users listed in the [`contacts`](w3c.json.md#contacts) property of the `w3c.json` file in the repo. + +When it gets flagged as not OK because the contributor could not be automatically associated with a W3C profile, the contributor will also be notified to ask them to [connect their W3C & GitHub accounts](https://www.w3.org/users/myprofile/connectedaccounts/). + +## Currently Open Pull Requests + +This list all PRs that are now open, even old ones. It lists useful details such as which users are being problematic either because they are unknown (not in the system at all) or outside (known to the system but not in one of the right groups for that repo). + +You can go to PR details by clicking "Details". + +## PR Details + +If the PR is not in an acceptable state, this will list problematic users with possible options to fix each of them, and a button to "Mark the PR as non-[substantive](https://www.w3.org/policies/process/#substantive-change)". + +The vast majority of non-acceptable PRs for a newly added repo will come from people whose W3C profile is not known (and thus neither are their affiliation and associated IPR commitments). + +When all problematic users have had their W3C profile associated, return to the PR details page and hit "Revalidate". We hope in the future to [revalidate every time a user is added or edited](https://github.com/w3c/ash-nazg/issues/26). Revalidation will of course update both the local state and the PR's mergability indicator on GitHub. + +## Active Last Week PRs + +This is a list of pull requests, in any state, that saw activity last week. They can be filtered according to the affiliation of the companies that made the contributions. This is essentially so that AC reps who have people in CGs who are only supposed to contribute to some specific work but not all of it can monitor what's been going on and avail themselves of their 45 days retraction window. Similar affordances are available as for the list of open PRs. + +## Edit User + +**Login required** + +In most cases, this interface will not be needed - it is only useful for cases where it is not possible or practical for a GitHub user to [associate their GitHub account with their W3C account](https://www.w3.org/users/myprofile/connectedaccounts/). + +The interface to edit users is where the W3C data model and the GitHub data model get to meet. This alone is scary; I've tried to make it less scary. + +A list of the groups known to the system is shown, the user can be added and removed from them there. If the user's affiliation is unset, once some groups have been added you can click "Set". This will load up a list that is the **intersection** of membership in the selected groups. The UI will also try to select the user with the name matching their GitHub profile (which may not always work, but often does). Hitting "OK" will associate the GitHub user with the W3C user, making it possible for us to use affiliation information. Don't forget to hit "Save". + +## Users list + +**Admin required** + +This is the list of users availble from "Admin > Users". Things you can do there include making them admins and giving them blanket contribution rights. **USE EITHER WITH CARE**. + +Admins should normally not be able to break the system, but they can enter all sorts of bogus information that would be really annoying. Only grant admin when you're sure; it's probably better to ask others first. + +Blanket is a different type of superpower. Users with blanket access are considered acceptable contributors to ALL repos, irrespective of their group memberships. This should normally be restricted to W3C Team people. + +## Groups list + +**Admin required** + +This is a list of all W3C groups availble from "Admin > Groups". You will note that most have an "Add" button next to them: those are the ones that are in W3C but not in this system. Please do **not** start adding groups unless they explicitly want to be managed under this system. We only want people to create/import repos for groups that are actually using this system. Clicking "Add" makes that group one of those available for repos and users to belong to. + +The source is at [https://github.com/w3c/ash-nazg](https://github.com/w3c/ash-nazg). diff --git a/github/repo-transfer.html b/github/repo-transfer.html deleted file mode 100644 index d9f3f2685..000000000 --- a/github/repo-transfer.html +++ /dev/null @@ -1,67 +0,0 @@ - - - - - - Transfer a repository to the W3C GitHub organization - - - -
-

Transfer a repository to the W3C GitHub organization

-
- - -
-

This document describes how to transfer a repository to the W3C GitHub organization.

-

See also general information about GitHub repo transfer.

-
    -
  1. Make sure the W3C GitHub organization doesn't already have a repository with the same name. If the name is already taken, the owner will need to rename the repository first -
  2. The repository owner initiates the transfer. This is done via the repo settings (see screen shot below): -
      -
    • if the owner is a W3C staff, they can transfer the repository directly to the W3C organization -
    • if the owner is an individual that cannot create new repository under the W3C organization, they need to transfer the repository to a W3C staff who will then transfer to the organization -
    • if the owner is another organization, a W3C staff first needs to join the organization as an owner or admin of the repository to make the transfer and that staff will issue the transfer to the W3C organization -
    - -
- -

Once the transfer is done, the next steps vary depending on the nature of the repository (specifications development or tooling).

-
    -
  • if the repository is about specifications development, it needs to be tracked by the W3C repository manager to help ensure that contributions are properly managed under W3C patent policies. To add a repository to the W3C repository manager, someone with admin rights on the repository needs to import it via the "import" tool. The repository manager will offer to add some files (w3c.json, CONTRIBUTING.md, LICENSE.md, etc) if they don't already exist and will add a webhook to the repository.
    - Be careful to select the right link to log in to the repository manager.
    -
    - -
  • if the repository is not about specifications development, you only need to add a file w3c.json at the root of the repository -
- -

If the repository contained a specification published through GitHub Pages, also consider adding redirects because Cool URIs don't change! When you transfer a repository, GitHub automatically redirects GitHub repo links (https://github.com/[org]/[repo]) but it does not redirect GitHub Pages links (https://[org].github.io/[repo]). That breaks former links to the specification. There is no direct way to create a redirect for GitHub Pages but the following steps can be used to redirect https://[org].github.io/[repo]/ to https://w3c.github.io/[repo]/:

-
    -
  • Create a [org].github.io repository under [org] if it does not exist already.
    • -
  • Create a [repo] folder in the [org].github.io repository.
    • -
  • Add an index.html file under the [repo] folder, which contains the following HTML code: -
    - 
    <!DOCTYPE html>
-<script>
-  const currentHash = window.location.hash;
-  const newLocation = "https://w3c.github.io/[repo]/" + currentHash;
-  window.location = newLocation;
-</script>
-
    • -
-

See the wicg.github.io repository for examples of redirects set in place when WICG repositories transition to the W3C organization.

-
- - - diff --git a/github/repo-transfer.md b/github/repo-transfer.md new file mode 100644 index 000000000..7bb6e1852 --- /dev/null +++ b/github/repo-transfer.md @@ -0,0 +1,43 @@ +--- +title: Transfer a repository to the W3C GitHub organization +toc: false +--- + +This document describes how to transfer a repository to the [W3C GitHub organization](https://github.com/w3c/). + +[See also general information about GitHub repository transfer](https://docs.github.com/en/github/administering-a-repository/transferring-a-repository). + +1. Make sure the [W3C GitHub organization](https://github.com/w3c/) doesn't already have a repository with the same name. If the name is already taken, the owner will need to rename the repository first +1. The repository owner initiates the transfer. This is done via the repo settings (see screenshot below): + + - If the owner is a W3C staff, they can transfer the repository directly to the W3C organization + - If the owner is an individual that cannot create new repository under the W3C organization, they need to transfer the repository to a W3C staff who will then transfer to the organization + - If the owner is another organization, a W3C staff first needs to join the organization [as an owner or admin of the repository](https://docs.github.com/en/github/administering-a-repository/transferring-a-repository#transferring-a-repository-owned-by-your-organization) to make the transfer and that staff will issue the transfer to the W3C organization + + ![GitHub repository transfer](img/github-transfer.png) + +1. Once the transfer is done, the next steps vary depending on the nature of the repository (specifications development or tooling). + + - **If the repository is about specifications development**, it needs to be tracked by the [W3C repository manager](https://labs.w3.org/repo-manager/) to help ensure that contributions are properly managed under W3C patent policies. To add a repository to the W3C repository manager, someone with admin rights on the repository needs to import it via the ["import" tool](https://labs.w3.org/repo-manager/repo/import). The repository manager will offer to add some files (`w3c.json`, `CONTRIBUTING.md`, `LICENSE.md`, etc) if they don't already exist and will add a webhook to the repository. + **Be careful to select the right link to log in to the repository manager**. + ![Repository manager login](img/repo-manager-login.png) + ![Repository manager import](img/repo-manager-import.png) + - **If the repository is not about specifications development**, you only need to add a file [`w3c.json`](/w3c.json.md) at the root of the repository. + +1. If the repository contained a specification published through GitHub Pages, also **consider adding redirects** because [Cool URIs don't change](https://www.w3.org/Provider/Style/URI)! + + When you transfer a repository, GitHub automatically redirects GitHub repo links (`https://github.com/[org]/[repo]`) but it does not redirect GitHub Pages links (`https://[org].github.io/[repo]`). That breaks former links to the specification. There is no direct way to create a redirect for GitHub Pages but the following steps can be used to redirect `https://[org].github.io/[repo]/` to `https://w3c.github.io/[repo]/`: + + - Create a `[org].github.io` repository under `[org]` if it does not exist already. + - Create a `[repo]` folder in the `[org].github.io` repository. + - Add an `index.html` file under the `[repo]` folder, which contains the following HTML code: + + ```html + + + ``` + See the [wicg.github.io repository](https://github.com/WICG/wicg.github.io) for examples of redirects set in place when WICG repositories transition to the W3C organization. diff --git a/github/specs.html b/github/specs.html deleted file mode 100644 index 3b1067dab..000000000 --- a/github/specs.html +++ /dev/null @@ -1,98 +0,0 @@ - - - - - - Using GitHub for Spec Work - - - - -
-

Using GitHub for Spec Work

-
- - -
-
    -
  1. -

    - Create a new GitHub repository using - the W3C Repository Manager. - The spec's shortname in lowercase is usually a good choice. -

    -
    2. -
  2. -

    - Once the new repository is created, find it on GitHub and set up - GitHub Pages - to use the default branch, main (Settings / Options / GitHub Pages). -

    -

    GitHub Pages settings of a repository

    -

    The repository's contents will get automagically served from https://username.github.com/reponame.

    -

    ⚠️ NB: be aware that GitHub Pages have some limitations.

    -
    3. -
  3. -

    - Clone the repository locally. -

    - 
    git clone https://github.com/tobie/specs-on-github.git
    -
    4. -
  4. -

    - Navigate to the repo. -

    - 
    cd specs-on-github
    -
    5. -
  5. -

    - Now we want to create the spec document itself. I use ReSpec, so I simply curl the content of the - default template into an index.html page at the root of my repository. -

    - 
    curl https://www.w3.org/respec/examples/template.html > index.html
    -
    6. -
  6. -

    - We can then add it to the repository. -

    - 
    git add index.html
-git commit -m "Add empty doc."
    -
    7. -
  7. -

    - Lets now push these changes back to our GitHub account. -

    - 
    git push origin main
    -

    - The first time you push changes it can take a little while for the code - to be published to your subdomain, so be patient. But it'll be ready soon enough. -

    -
    8. -
  8. -

    - Set up your favorite labels -

    -
    9. -
  9. -

    - Bask in the glory of modern spec development. -

    -
    10. -
-

(For help and tips about Git itself, refer to the dedicated page.)

-
- - - diff --git a/github/specs.md b/github/specs.md new file mode 100644 index 000000000..9d8a78240 --- /dev/null +++ b/github/specs.md @@ -0,0 +1,41 @@ +--- +title: Using GitHub for Spec Work +toc: false +--- + +1. [Create a new GitHub repository](https://labs.w3.org/repo-manager/repo/new) using the [W3C Repository Manager](https://labs.w3.org/repo-manager/). The spec's *shortname* in lowercase is usually a good choice. +1. Once the new repository is created, find it on GitHub and set up [GitHub Pages](https://github.blog/developer-skills/application-development/simpler-github-pages-publishing/) to use the default branch, `main` (*Settings* / *Options* / *GitHub Pages*). + + ![GitHub Pages settings of a repository](img/gh-settings.png) + + The repository's contents will get *automagically* served from `https://username.github.com/reponame`. + + ⚠️ **NB:** be aware that [GitHub Pages have some limitations](faq.md#drafts). +1. Clone the repository locally. + + ```shell + git clone https://github.com/username/reponame.git + ``` +1. Navigate to the repo. + + ```shell + cd reponame + ``` +1. **Note: this step and the following are not needed if you set up your repository using the W3C Repository Manager as it can create a basic ReSpec document for you**. +Now we want to create the spec document itself. I use [ReSpec](https://respec.org/docs/), so I simply copy the content of the [default template](https://respec.org/docs/#getting-started) into an `index.html` page at the root of my repository. And then add it to the repository. + + ```shell + git add index.html + git commit -m "Add empty doc." + ``` +1. Lets now push these changes back to our GitHub account. + + ```shell + git push origin main + ``` + + The first time you push changes it can take a little while for the code to be published to your GitHub Pages subdomain, so be patient. But it'll be ready soon enough. +1. Set up your [favorite labels](issue-metadata.md) +1. Bask in the glory of modern spec development. + +(For help and tips about Git itself, refer to [the dedicated page](git.md).) diff --git a/github/w3c.json.html b/github/w3c.json.html deleted file mode 100644 index 1aaaeab41..000000000 --- a/github/w3c.json.html +++ /dev/null @@ -1,147 +0,0 @@ - - - - - - The w3c.json file - - - -
-

The w3c.json file

-
- - -
-

- Projects operating under the w3c organisation (or related to W3C even if under - other umbrellas) are encouraged to specify a w3c.json file at the root of their - repository. The purpose of this file is to provide some metadata about repositories so that - they can be processed automatically by a variety of tools layered atop - the organisation. - They can also help humans figure out who to contact for a given problem. -

-

- Here is an example: -

- 
{
-    "group":     "wg/webrtc"
-,   "contacts":  ["dontcallmedom"]
-,   "repo-type": "rec-track"
-}
-

- The fields that are understood at this point are: -

-
-
group
-
- The "/"-separated concatenation of group-type ("wg", "cg", "ig", "bg", "tf", "other") and shortname of the group or task force - in charge of this repository. If the repository is not linked to any group, do not include that field. If the repository is linked to multiple groups, use an array. - - 
"group": ["wg/css", "other/tag", "tf/i18n-jlreq"]
-
- -
contacts
-
- An array of people who are considered points of contact for the - repository for administrative requests. They aren't necessarily - the primary contributor and they aren't necessarily from the W3C - Team. Whatever works for any given repository is acceptable. - For integration purposes, please use your GitHub ID. -
- -
repo-type
-
- String to identify the type and purpose of the repository, or an array of such strings if the repository holds more than one type of content. - The possible values for this field are:

-
-
rec-track
-
W3C Recommendation Track Documents including First Public - Working Draft, Working Draft, Candidate Recommendation, Proposed - Recommendation and W3C Recommendation
- -
note
-
W3C Note Track including Group Draft Note, Group Note and Statement
- -
registry
-
W3C Registry Track including Draft Registry, Candidate Registry, Candidate Registry Draft, and Registry
- -
cg-report
-
W3C Community Group Report
- -
tests
-
Test suite work
- -
process
-
Work around W3C Process document, charters, policies
- -
workshop
-
Repo to manage W3C workshops
- -
homepage
-
Groups' homepages
- -
translation
-
Repo hosting translation of a spec or other documents
- -
article
-
Non-spec documents
- -
tool
-
Development of tools
- -
project
-
Group-independent projects
- -
others
-
Other purposes
-
-
- -
policy
-
- This is essentially a W3C-internal flag. If set to open, any W3C Team member - should feel empowered to help with the management of this given repository. This can be - set to restricted to indicate that for whatever reason, it is preferable to - let the repository be handled only by team contacts directly associated with it. The - default value is open. -
- -
exposed
-
- This flag indicates if a repository gets exposed in the W3C group pages. - By default, all public repositories will get exposed (exposed:true) and all private repositories - will not get exposed (exposed:false). -
-
-

Tooling

- -

- There is a variety of tools using the w3c.json files. -

-

Groups

- -

- The tools pages of all of the W3C related groups, such as - WICG or - VC are generated using the - compiled set - of w3c.json files. See also the w3c/groups README. -

- -
- - - diff --git a/github/w3c.json.md b/github/w3c.json.md new file mode 100644 index 000000000..baf2d7bf8 --- /dev/null +++ b/github/w3c.json.md @@ -0,0 +1,84 @@ +--- +title: The w3c.json file +toc: false +--- + +Projects operating under the `w3c` organisation (or related to W3C even if under other umbrellas) are encouraged to specify a `w3c.json` file at the root of their repository. The purpose of this file is to provide some metadata about repositories so that they can be processed automatically by a [variety of tools](#tools) layered atop the organisation. They can also help humans figure out who to contact for a given problem. + +Here is an example: + +```json +{ + "group": "wg/webrtc" +, "contacts": ["dontcallmedom"] +, "repo-type": "rec-track" +} +``` + +The fields that are understood at this point are: + +`group` +: The "`/`"-separated concatenation of group-type ("`wg`", "`cg`", "`ig`", "`bg`", "`tf`", "`other`") and shortname of the [group or task force](https://www.w3.org/groups/) in charge of this repository. If the repository is not linked to any group, do not include that field. If the repository is linked to multiple groups, use an array. + + ```json + "group": ["wg/css", "other/tag", "tf/i18n-jlreq"] + ``` + +`contacts` +: An array of people who are considered points of contact for the repository for administrative requests. They aren't necessarily the primary contributor and they aren't necessarily from the W3C Team. Whatever works for any given repository is acceptable. For integration purposes, please use your *GitHub* ID. + +`repo-type` +: String to identify the type and purpose of the repository, or an array of such strings if the repository holds more than one type of content. The possible values for this field are: + + `rec-track` + : [W3C Recommendation Track](https://www.w3.org/policies/process/#rec-track) documents including First Public Working Draft, Working Draft, Candidate Recommendation, Proposed Recommendation and W3C Recommendation + + `note` + : [W3C Note Track](https://www.w3.org/policies/process/#note-track) documents including Group Draft Note, Group Note and Statement + + `registry` + : [W3C Registry Track](https://www.w3.org/policies/process/#registries) documents including Draft Registry, Candidate Registry, Candidate Registry Draft, and Registry + + `cg-report` + : W3C Community Group Report + + `tests` + : Test suite work + + `process` + : Work around W3C Process document, charters, policies + + `workshop` + : Management of W3C workshops + + `homepage` + : Groups' homepages + + `translation` + : Translation of a spec or other documents + + `article` + : Non-spec documents + + `tool` + : Development of tools + + `project` + : Group-independent projects + + `others` + : Other purposes + +`policy` +: This is essentially a W3C-internal flag. If set to `open`, any W3C Team member should feel empowered to help with the management of this given repository. This can be set to `restricted` to indicate that for whatever reason, it is preferable to let the repository be handled only by team contacts directly associated with it. The default value is `open`. + +`exposed` +: This flag indicates if a repository gets exposed in the [W3C group pages](https://www.w3.org/groups/). By default, all public repositories will get exposed (`exposed:true`) and all private repositories will not get exposed (`exposed:false`). + +## Tooling {#tools} + +There is a variety of tools using the `w3c.json` files. + +### Groups + +The tools pages of all of the W3C related groups, such as [WICG](https://www.w3.org/groups/cg/wicg/tools/) or [VC](https://www.w3.org/groups/wg/vc/tools/) are generated using the [compiled set of `w3c.json` files](https://w3c.github.io/groups/repositories.json). See also the [w3c/groups README](https://github.com/w3c/groups/blob/main/README.md). diff --git a/github/workflow.html b/github/workflow.html deleted file mode 100644 index 896919ab1..000000000 --- a/github/workflow.html +++ /dev/null @@ -1,157 +0,0 @@ - - - - - - Workflow for editors and other contributors - - - - -
-

Workflow for editors and other contributors

-
- - -
-

- A good practice for GitHub is to use pull requests. - It lets you propose changes to others without making changes to the main branch of the repository. - Once a pull request is opened, you can discuss and review the potential changes with - others and add follow-up commits before the changes are merged into the repository. -

-
    -
  1. -

    - Navigate to the repo. -

    - 
    cd specs-on-github
    -
    2. -
  2. -

    - Checkout the main branch of your repository (in general, this is the main branch). -

    - 
    git checkout main
    -
    3. -
  3. -

    - Make sure the main branch is up-to-date with upstream. -

    - 
    git pull
    -

    - If you forked the repository on GitHub, you may need to indicate the upstream repository more explicitly. -

    -
    4. -
  4. -

    - Create a new branch for your upcoming pull request (one branch per pull request). Please make branch names - informative - by including the issue or bug number for example. -

    - 
    git checkout -b my-wonderful-edits-for-87
    -
    5. -
  5. -

    - Make your edits in your favorite editor. -

    -
    6. -
  6. -

    - Add your edits to prepare your commit by staging them. - This will help you to easily craft your commits to include only certain combinations and parts of files. - Best is to use the interactive patch mode (new files still need to be added explicitly), where you can select which change should - be part of the commit. This allows you to make multiple edits at once and split them into different more - meaningful/easy-to-review commits. -

    - 
    git add -p
    -
    7. -
  7. -

    - Commit your staged edits. If you're fixing an issue, reference it in the commit e.g. fix #87 - (if you write close or fix, it will automatically close the issue once the commit is added to the main branch). -

    - 
    git commit -m "<purpose of your edits> (fix #number)"
    -

    This command allows you to replace the last commit with a new one, if you feel the need to change it:

    - 
    git commit --amend
    -
    8. -
  8. -

    - Once all your commits are done, push your branch upstream. -

    - 
    git push --set-upstream origin my-wonderful-edits-for-87
    -
    9. -
  9. -

    - Using your favorite browser, navigate to the repo on GitHub, e.g. -

    - 
    https://github.com/tobie/specs-on-github/
    -
    10. -
  10. -

    - Once your authenticated on the repo page, a new button should appear on the page to create a new - pull request (Compare & pull request). Go ahead and punch it. -

    -

    Compare & pull request

    -
    11. -
  11. -

    - Make sure you like the title of your pull request, add a proper description (including mentioning the contributors with - "+@username"), and use - proper GitHub labels, add one or more reviewers so they get pinged. - Once you're satisfied, create the pull request. Note that you can update all of that information - after that if needed. -

    -
    12. -
  12. -

    - All normative spec changes are generally expected to have a corresponding pull request in - web-platforms-tests, - either in the form of new tests or modifications to existing tests, or must include the rationale for why test - updates are not required for the proposed update. -

    -

    - Typically, both pull requests (spec updates and tests) will be merged at the same time. If a pull request - for the specification is approved but the other needs more work, add the - 'needs tests' label or, - in web-platform-tests, the - 'status:needs-spec-decision' - label. Note that a test change that contradicts - the specification should not be merged before the corresponding specification change. -

    -

    - If testing is not practical due to web-platforms-tests limitations, - please explain why and if appropriate file an issue with the - 'type:untestable' - label to follow up later. For tests that aren't ready for the specification, you may use the .tentative filename convention. -

    -
    13. -
  13. -

    - Wait for the needed reviews. All pull requests must have been reviewed by one or more participants of the working group. - They can use approve changes, give you +1, comment, etc. You may need to make additional commits in your branch and push them - again in order to address the review. The pull request will keep tracking the branch so it will get automatically updated with the new commits. -

    -
    14. -
  14. -

    - Once the pull request gets enough support, it can be merged (you should use the Squash and merge to avoid cluttering the - commit history and consider cleaning up the commit message). Delete your ad-hoc branch my-wonderful-edits-for-87. You're done. -

    -
    15. -
-

(For help and tips about Git itself, refer to the dedicated page.)

-
- - - diff --git a/github/workflow.md b/github/workflow.md new file mode 100644 index 000000000..263f037c3 --- /dev/null +++ b/github/workflow.md @@ -0,0 +1,69 @@ +--- +title: Workflow for editors and other contributors +toc: false +--- + +A good practice for GitHub is to use [pull requests](https://help.github.com/articles/about-pull-requests/). It lets you propose changes to others without making changes to the `main` branch of the repository. Once a pull request is opened, you can discuss and review the potential changes with others and add follow-up commits before the changes are merged into the repository. + +1. Navigate to the repo. + + ```shell + cd specs-on-github + ``` +1. Checkout the main branch of your repository (in general, this is the `main` branch). + + ```shell + git checkout main + ``` +1. Make sure the main branch is up-to-date with upstream. + + ```shell + git pull + ``` + + If you forked the repository on GitHub, you may need to indicate the upstream repository more explicitly. +1. Create a new branch for your upcoming pull request (one branch per pull request). Please make branch names informative - by including the issue or bug number for example. + + ```shell + git checkout -b my-wonderful-edits-for-87 + ``` +1. Make your edits in your favorite editor. +1. Add your edits to prepare your commit by [staging](https://git-scm.com/book/en/v2/Git-Tools-Interactive-Staging) them. This will help you to easily craft your commits to include only certain combinations and parts of files. Best is to use the interactive patch mode (new files still need to be added explicitly), where you can select which change should be part of the commit. This allows you to make multiple edits at once and split them into different more meaningful/easy-to-review commits. + + ```shell + git add -p + ``` +1. Commit your staged edits. If you're fixing an issue, reference it in the commit e.g. `fix #87` (if you write close or fix, it will automatically close the issue once the commit is added to the main branch). + + ```shell + git commit -m " (fix #number)" + ``` + + This command allows you to replace the last commit with a new one, if you feel the need to change it: + + ```shell + git commit --amend + ``` +1. Once all your commits are done, push your branch upstream. + + ```shell + git push --set-upstream origin my-wonderful-edits-for-87 + ``` +1. Using your favorite browser, navigate to the repo on GitHub, e.g. + + ``` + https://github.com/tobie/specs-on-github/ + ``` +1. Once your authenticated on the repo page, a new button should appear on the page to create a new pull request (`Compare & pull request`). Go ahead and punch it. + + ![Compare & pull request](img/create-a-pr.png) +1. Make sure you like the title of your pull request, add a proper description (including mentioning the contributors with "[+@github_username](https://github.com/w3c/licenses/blob/main/SW-CONTRIBUTING.md)"), and use [proper GitHub labels](issue-metadata.md), add one or more reviewers so they get pinged. Once you're satisfied, create the pull request. Note that you can update all of that information after that if needed. +1. All normative spec changes are generally expected to have a corresponding pull request in [web-platforms-tests](https://github.com/w3c/web-platform-tests/), either in the form of new tests or modifications to existing tests, or must include the rationale for why test updates are not required for the proposed update. + + Typically, both pull requests (spec updates and tests) will be merged at the same time. If a pull request for the specification is approved but the other needs more work, add the '[needs tests](issue-metadata.md)' label or, in web-platform-tests, the '[status:needs-spec-decision](https://github.com/w3c/web-platform-tests/issues?utf8=%E2%9C%93&q=label%3Astatus%3Aneeds-spec-decision%20)' label. Note that a test change that contradicts the specification should not be merged before the corresponding specification change. + + If testing is not practical due to [web-platforms-tests](https://github.com/w3c/web-platform-tests/) limitations, please explain why and if appropriate file an issue with the '[type:untestable](https://github.com/w3c/web-platform-tests/issues?utf8=%E2%9C%93&q=label%3Atype%3Auntestable%20)' label to follow up later. For tests that aren't ready for the specification, you may use the [`.tentative` filename convention](http://web-platform-tests.org/writing-tests/file-names.html#test-features). +1. Wait for the needed reviews. All pull requests must have been reviewed by one or more participants of the working group. They can use approve changes, give you `+1`, comment, etc. You may need to make additional commits in your branch and push them again in order to address the review. The pull request will keep tracking the branch so it will get automatically updated with the new commits. +1. Once the pull request gets enough support, it can be merged (you should use the `Squash and merge` to avoid cluttering the commit history and consider cleaning up the commit message). Delete your ad-hoc branch `my-wonderful-edits-for-87`. You're done. + +For help and tips about Git itself, refer to [the dedicated page](git.md). diff --git a/teamcontact/role.md b/teamcontact/role.md index b6694beaf..c7a2c2b51 100644 --- a/teamcontact/role.md +++ b/teamcontact/role.md @@ -64,7 +64,7 @@ The Team Contact is also charged with representing the views of the Team to the - *Assist* Chair in coordinating with other W3C groups as needed. - *Ensure* liaisons between Group and other W3C groups are assigned as needed. - \[*Active Role*] Coordinate with the Systems Team to ensure that Chair and group Editors have appropriate access to the W3C site, and that their access works, e.g. GitHub. -- *Ensure* that Group editors understand how to use [GitHub at W3C](https://w3c.github.io/). +- *Ensure* that Group editors understand how to use [GitHub at W3C](../github/). - *Ensure*, before publishing any Group document in W3C/TR space, that it is: 1. Being published properly (see [Pubrules](https://www.w3.org/pubrules/)). diff --git a/tools/new-group.md b/tools/new-group.md index e2941c9bf..faf3b2a7d 100644 --- a/tools/new-group.md +++ b/tools/new-group.md @@ -16,17 +16,17 @@ Having an administrivia repository allows to track and maintain potential non-te - homepage - etc. -For this repository, you may use the naming convention ***`w3c/{shortname}{type}`***, such as ***`w3c/privacywg`***. Don't forget to set the [`w3c.json` file](https://w3c.github.io/w3c.json.html) appropriately (***`repo-type: "project"`***). +For this repository, you may use the naming convention ***`w3c/{shortname}{type}`***, such as ***`w3c/privacywg`***. Don't forget to set the [`w3c.json` file](../github/w3c.json.md) appropriately (***`repo-type: "project"`***). ## 2. Group homepage {#homepage} By default, the W3C website will have a homepage for the Group, maintained by various W3C systems and accessible through the [Group pages](https://www.w3.org/groups/). For simplicity and ease of maintenance, we recommend that you point your participants to that group page. Additional links can be added by the Team in the "Tools" page of the Group if needed. -However, if your group do feel the need to maintain a dedicated homepage, place it in your group administrivia repository and ask to expose it through w3.org as a proxy (Team should look at [W3C Web rewrites system](https://www.w3.org/2019/03/rewrites-doc.html)). Don't forget to set the [`w3c.json` file](https://w3c.github.io/w3c.json.html) appropriately (***`repo-type: "homepage"`***). +However, if your group do feel the need to maintain a dedicated homepage, place it in your group administrivia repository and ask to expose it through w3.org as a proxy (Team should look at [W3C Web rewrites system](https://www.w3.org/2019/03/rewrites-doc.html)). Don't forget to set the [`w3c.json` file](../github/w3c.json.md) appropriately (***`repo-type: "homepage"`***). ## 3. Github repositories {#repositories} -All GitHub repositories used by the group must indicate so, using the [`w3c.json` file](https://w3c.github.io/w3c.json.html) in those repositories. If you do not use the GitHub 'w3c' organization, make sure the Team associates your GitHub organization in the 'Version Control' entry of the Tools page (Team may modify those entries using the [admin](https://w3.org/admin) interface) and the tooling will associate *by default* all of the repositories in your GitHub organization to your group. +All GitHub repositories used by the group must indicate so, using the [`w3c.json` file](../github/w3c.json.md) in those repositories. If you do not use the GitHub 'w3c' organization, make sure the Team associates your GitHub organization in the 'Version Control' entry of the Tools page (Team may modify those entries using the [admin](https://www.w3.org/admin) interface) and the tooling will associate *by default* all of the repositories in your GitHub organization to your group. Make sure the license and code of conduct files are there (Team, you may use the [repository manager](https://labs.w3.org/repo-manager/) to create those).