Add contributing guide

CONTRIBUTING.md

@@ -0,0 +1,245 @@
+# Solid Technical Reports Contributing Guide
+
+Thank you for investing your time in contribution to the Solid project!
+
+This repository contains the source code of the work on [Solid Technical
+Reports](https://solidproject.org/TR/) (TR) of the [W3C Solid Community
+Group](https://www.w3.org/community/solid/) (CG) to meet the needs of the [Solid
+Project](https://solidproject.org/).
+
+The TRs include specifications, use cases and requirements, best practices and
+guidelines, primers and notes about the Solid ecosystem.
+
+
+## Code of conduct
+
+Read the [Solid Code of
+Conduct](https://github.com/solid/process/blob/main/code-of-conduct.md) and the
+[Positive Work Environment at W3C: Code of Ethics and Professional
+Conduct](https://www.w3.org/Consortium/cepc/) to keep our community approachable
+and respectable.
+
+
+## Contributions
+
+In order to be a substantive contributor to work items, you must be a member of
+the CG. It’s easy to [join the CG](https://www.w3.org/community/solid/join) if
+you’d like to contribute. People agree to the [W3C Community License Agreement
+(CLA)](http://www.w3.org/community/about/agreements/cla/) upon joining the CG.
+
+The works in this repository use the [MIT
+license](https://github.com/solid/specification/blob/main/LICENSE.md).
+
+We accept different types of contributions as described below.
+
+### Discussions
+
+If you'd like help troubleshooting a pull request (PR) you're working on, have a
+great new idea, or want to share implementation feedback, join us in [Solid
+specification chat](https://gitter.im/solid/specification).
+
+### Issues
+
+[Issues](https://docs.github.com/en/github/managing-your-work-on-github/about-issues)
+are used to track tasks that contributors can help with. If an issue has a
+triage label, we haven't reviewed it yet and you shouldn't begin work on it.
+
+If you've found something in the content or the website that should be updated,
+search open issues to see if someone else has reported the same thing. If it's
+something new, open an issue. We'll use the issue to have a conversation about
+the problem you want to fix.
+
+### Pull requests
+
+A [pull
+request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests)
+is a way to suggest changes in our repository.
+
+### Translations
+
+We aim to have our documents internationalized and available in multiple
+languages. The source content in this repository is written in English. We
+accept contributions to localize the English content.
+
+
+## Contributions at source repository
+
+Each CG work item listed at [Solid Technical
+Reports](https://solidproject.org/TR/) has its own repository and any issues
+and PRs should be made at their source.
+
+The persistent version of technical reports published in this repository (see
+[publishing technical reports](#publishing-technical-reports) are intended to
+be read-only snapshots of the CG work items.
+
+[Solid
+Panels](https://github.com/solid/specification/blob/main/README.md#solid-panels)
+focus on certain work streams, with an aim to propose technical reports for
+the Solid ecosystem.
+
+A low-barrier way to add concrete suggestions is to submit a [user
+story](https://github.com/solid/user-stories). User stories are descriptions of desired features written in a special way, see the description there for details. User stories may then be used when formulating use cases and requirements.
+
+
+## Creating and solving issues
+
+### Create a new issue
+
+If you spot a problem with the technical reports being worked on in this
+repository or would like to request a feature, [search if an issue already
+exists](https://docs.github.com/en/github/searching-for-information-on-github/searching-on-github/searching-issues-and-pull-requests#search-by-the-title-body-or-comments).
+If a related issue doesn't exist, you can open a new issue. In the issue,
+include relevant information that can help others, e.g., links to
+specifications, issues, implementations, test suite, discussions.
+
+### Solve an issue
+
+Scan through our [existing
+issues](https://github.com/solid/specification/issues/) to find one that
+interests you. You can narrow down the search using `labels` as filters. See
+[Labels](https://github.com/github/docs/blob/main/contributing/how-to-use-labels.md)
+for more information. If you find an issue to work on, you are welcome to open
+a PR with a fix.
+
+
+## Make changes
+
+### Make changes locally
+
+1. Install Git
+2. Fork the repository.
+3. Create a working branch and start with your changes!
+
+
+## Commit your update
+
+Commit the changes once you are happy with them. See [Atom's contributing
+guide](https://github.com/atom/atom/blob/master/CONTRIBUTING.md#git-commit-messages)
+to know how to use emoji for commit messages.
+
+Once your changes are ready, don't forget to [self-review](#self-review) to
+speed up the review process:zap:.
+
+### Self-review
+
+You should always review your own PR first.
+
+For content changes, make sure that you:
+
+* [ ] Confirm that the changes meet the user experience and goals outlined in
+  the content design plan (if there is one).
+* [ ] Compare your PR's source changes to staging to confirm that the
+  output matches the source and that everything is rendering as expected. The
+  W3C service to [creating diff between HTML pages](https://services.w3.org/htmldiff)
+  can also be used.
+* [ ] Review the content for technical accuracy.
+* [ ] Review the entire PR using the [localization
+  checklist](https://github.com/github/docs/blob/main/contributing/localization-checklist.md)
+  and the [W3C Manual of Style](https://www.w3.org/2001/06/manual/) as guides.
+* [ ] If there are any failing checks in your PR, troubleshoot them until
+  they're all passing.
+
+
+## Creating a pull request
+
+When you're finished with the changes to documents that are maintained in this
+repository, create a PR.
+
+* Include atomic commits, small PRs: "one concern, one PR".
+* In the PR comment, provide as much context and evidence to help reviewers
+  evaluate the PR.
+* Don't forget to [link PR to
+  issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue)
+  if you are solving one.
+* We may ask for changes to be made before a PR can be merged, either using
+  [suggested
+  changes](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/incorporating-feedback-in-your-pull-request)
+  or PR comments. You can apply suggested changes directly through the UI. You
+  can make any other changes in your fork, then commit them to your branch.
+* As you update your PR and apply changes, mark each conversation as
+  [resolved](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request#resolving-conversations).
+* If you run into any merge issues, checkout this [git
+  tutorial](https://lab.github.com/githubtraining/managing-merge-conflicts) to
+  help you resolve merge conflicts and other issues.
+* If you are not the sole contributor, please identify all contributors in the
+  PR comment. To add a contributor (other than yourself), mark them one per
+  line as follows: `+@github_username`.
+
+### Your PR is merged!
+
+Congratulations :tada: Solid community thanks you :sparkles:.
+
+
+
+## Publishing a technical report
+
+This section describes how to prepare the technical reports and how they'll be
+published on the Solid website.
+
+### General guidance
+
+* Content: the full content of the technical report must be human-readable with
+  HTML alone. Any CSS and JavaScript should not interfere with the accessibility
+  of the content.
+* Offline-friendly: there must not be any mandatory external dependencies (e.g., a network
+  connection) to retrieve, to render, or to manipulate the content of the
+  article.
+* Privacy: scripts must not be used to identify or track readers.
+
+There are two parts to publishing a technical report that applies to all
+reports:
+
+1. PR including the technical report in HTML and all local script and media
+   files.
+2. Updating the technical report index (if necessary).
+
+Published documents will be publicly accessible under the paths
+`https://solidproject.org/TR/` or `https://solidproject.org/ED/`.
+
+### Versioned technical report
+
+The PR for a versioned technical report must include two HTML documents:
+
+1. "Latest version" of the TR under the root (`/`) directory.
+2. "Persistent version" of the TR under the `/{yyyy}/` (year in 4 digits)
+   directory.
+
+We recommend that the latest version of the technical reports use a
+`{shortname}`, e.g., `protocol`, `wac`, and the persistent version of the
+technical report follows the following form: `{shortname}-{yyyymmdd}`.
+
+All files use common file name extensions, e.g., `.html`.
+
+The documents will be published under the path `https://solidproject.org/TR/`.
+
+For example, the *Solid Protocol* is available from the following URLs:
+* Latest version: https://solidproject.org/TR/protocol
+* Persistent version: https://solidproject.org/TR/2021/protocol-20211217
+
+When a new version of the technical report is made available, we follow the same
+process. The new "latest version" will then link to the new "persistent
+version". Every persistent version will link to the latest version.
+
+### Non-versioned technical report
+
+The PR for a non-versioned technical report must include one HTML document and
+follow the same requirements as in "latest version" (see [versioned technical
+report](#versioned-technical-report)).
+
+The documents will be published under the path `https://solidproject.org/TR/`.
+
+### Editor's draft
+
+The PR for a non-versioned technical report must include one HTML document and
+follow the same requirements as in "latest version" (see [versioned technical
+report](#versioned-technical-report)).
+
+The document will be published under the path `https://solidproject.org/ED/`.
+For example, the Editor's Draft of the *Solid Protocol* is available from
+https://solidproject.org/ED/protocol .
+
+## Technical Report index
+
+When a new technical report is added, information about it is modified, or a
+new work item is being worked on by the CG, a PR should update the [Technical
+Report index](https://github.com/solid/specification/blob/main/index.html).

README.md

@@ -23,6 +23,10 @@ Solid Panels focus on specific problems, with an aim to propose technical report
 * https://github.com/solid/notifications-panel
 * https://github.com/solid/test-suite
 
+## Contributing
+
+See the [contributing guide](https://github.com/solid/specification/blob/main/CONTRIBUTING.md) for detailed instructions on how to get started with our project.
+
 ## Code of Conduct
 
 All work and communication within the Solid CG is covered by the [Solid Code of Conduct](https://github.com/solid/process/blob/main/code-of-conduct.md) as well as the [Positive Work Environment at W3C: Code of Ethics and Professional Conduct](https://www.w3.org/Consortium/cepc/).