diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..3b5c6b50 --- /dev/null +++ b/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). diff --git a/README.md b/README.md index d47cdeea..3815a606 100644 --- a/README.md +++ b/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/).