Improve documentation

* Add more information to collectors, formatters, and rules to dev and user guide. * Update "Code of Conduct" to the JS Foundation one. * Update list of rules. * Fix typo in `disown-opener` rule documentation. * Update references to GitHub issues and PR. * Whitelist final repo in awesome-bot. * Update links to Internet Archive version of speakup.io. - - - - - - - - - - - - - - - - - - - - - - Fix #225 Fix #266
webhintio · Jun 19, 2017 · b613918 · b613918
1 parent beaca1b
commit b613918
Show file tree

Hide file tree

Showing 26 changed files with 670 additions and 379 deletions.
diff --git a/.travis/check-links.sh b/.travis/check-links.sh
@@ -13,5 +13,5 @@ find . -name "*.md" \
                 --allow-dupe \
                 --allow-redirect \
                 --set-timeout 150 \
-                --white-list "example1.com,example2.com,example3.com" \
+                --white-list "example1.com,example2.com,example3.com,github.com/sonarwhal/" \
                 {} +
diff --git a/LICENSE.txt b/LICENSE.txt
@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright {yyyy} {name of copyright owner}
+   Copyright 2017 JS Foundation
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

diff --git a/docs/about/CHANGELOG.md b/docs/about/CHANGELOG.md
@@ -1,9 +1,3 @@
----
-title: Changelog | sonar
-tocTitle: changelog
-category: about
-permalink: about/changelog.html
----
 # Changelog
 
 sonar is currently in active development with lots of moving pieces. Once it

diff --git a/docs/about/CODE_OF_CONDUCT.md b/docs/about/CODE_OF_CONDUCT.md
@@ -1,85 +1,98 @@
----
-title: Contributor Covenant Code of Conduct | sonar
-tocTitle: code-of-conduct
-category: about
-permalink: about/code-of-conduct.html
----
-# Contributor Covenant Code of Conduct
-
-## Our Pledge
-
-In the interest of fostering an open and welcoming environment, we
-as contributors and maintainers pledge to making participation in our
-project and our community a harassment-free experience for everyone,
-regardless of age, body size, disability, ethnicity, gender identity
-and expression, level of experience, nationality, personal appearance,
-race, religion, or sexual identity and orientation.
-
-## Our Standards
-
-Examples of behavior that contributes to creating a positive
-environment include:
-
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy towards other community members
-
-Examples of unacceptable behavior by participants include:
-
-* The use of sexualized language or imagery and unwelcome sexual
-  attention or advances
-* Trolling, insulting/derogatory comments, and personal or political
-  attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or
-  electronic address, without explicit permission
-* Other conduct which could reasonably be considered inappropriate
-  in a professional setting
-
-## Our Responsibilities
-
-Project maintainers are responsible for clarifying the standards
-of acceptable behavior and are expected to take appropriate and fair
-corrective action in response to any instances of unacceptable behavior.
-
-Project maintainers have the right and responsibility to remove,
-edit, or reject comments, commits, code, wiki edits, issues, and other
-contributions that are not aligned to this Code of Conduct, or to ban
-temporarily or permanently any contributor for other behaviors that
-they deem inappropriate, threatening, offensive, or harmful.
-
-## Scope
-
-This Code of Conduct applies both within project spaces and in public
-spaces when an individual is representing the project or its community.
-Examples of representing a project or community include using an
-official project e-mail address, posting via an official social media
-account, or acting as an appointed representative at an online or
-offline event. Representation of a project may be further defined and
-clarified by project maintainers.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior
-may be reported by contacting the project team at
-[antonmo@microsoft.com](mailto:antonmo@microsoft.com) or
-[catalin.maris@microsoft.com](mailto:catalin.maris@microsoft.com).
-All complaints will be reviewed and investigated and will result in a
-response that is deemed necessary and appropriate to the circumstances.
-The project team is obligated to maintain confidentiality with regard
-to the reporter of an incident. Further details of specific enforcement
-policies may be posted separately.
-
-Project maintainers who do not follow or enforce the Code of Conduct in
-good faith may face temporary or permanent repercussions as determined
-by other members of the project's leadership.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant][homepage],
-version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
-
-[homepage]: http://contributor-covenant.org
-[version]: http://contributor-covenant.org/version/1/4/
+# Code of Conduct
+
+Like the technical community as a whole, the various JS Foundation teams and
+communities are made up of a mixture of professionals and volunteers from all
+over the world, working on every aspect of the mission - including mentorship,
+teaching, and connecting people.
+
+Diversity is one of our huge strengths, but it can also lead to communication
+issues and unhappiness. To that end, we have a few ground rules that we ask
+people to adhere to. This code applies equally to founders, mentors and those
+seeking help and guidance.
+
+This isn't an exhaustive list of things that you can't do. Rather, take it in
+the spirit in which it's intended - a guide to make it easier to enrich all of
+us and the technical communities in which we participate.
+
+This Code of Conduct applies to all spaces managed by the JS Foundation and its
+projects. This includes IRC, the mailing lists, the issue trackers, JS
+Foundation events, and any other forums created by the project teams which the
+community uses for communication. In addition, violations of this code outside
+these spaces may affect a person's ability to participate within them.
+
+If you believe someone is violating the Code of Conduct, we ask that you report
+it by emailing [conduct@js.foundation][mailto:conduct@js.foundation]. For more
+details, please see our [Reporting Guidelines](https://js.foundation/community/code-of-conduct/reporting).
+
+## Be friendly and patient
+
+We understand that everyone has different levels of experience or knowledge in
+many diverse fields, be it technical or non-technical in nature. We also have
+areas of knowledge we are eager to expand; we want to be a community where
+people can not only contribute, but feel comfortable to ask questions as well
+and learn along the way. If someone says something wrong, or says something
+accidentally offensive, respond with patience and try to keep it polite and
+civil. Remember that we all were newbies at one point.
+
+## Be welcoming
+
+We strive to be a community that welcomes and supports people of all
+backgrounds and identities. This includes, but is not limited to, members of any
+race, ethnicity, culture, national origin, color, immigration status, social and
+economic class, educational level, sex, sexual orientation, gender identity and
+expression, age, size, family status, political belief, religion, and mental
+and physical ability.
+
+## Be considerate
+
+Your work will be used by other people, and you in turn will depend on the work
+of others. Any decision you make will affect users and colleagues, and you
+should take those consequences into account when making decisions. Remember
+that we're a world-wide community, so you might not be communicating in someone
+else's primary language.
+
+## Be respectful
+
+Not all of us will agree all the time, but disagreement is no excuse for poor
+behavior and poor manners. We might all experience some frustration now and
+then, but we cannot allow that frustration to turn into a personal attack. It's
+ important to remember that a community where people feel uncomfortable or
+ threatened is not a productive one. Members of the JS Foundation community
+ should be respectful when dealing with other members as well as with people
+ outside the JS Foundation community.
+
+## Be careful in the words that you choose
+
+We are a community of professionals, and we conduct ourselves professionally.
+Be kind to others. Do not insult or put down other participants. Harassment and
+other exclusionary behavior aren't acceptable. This includes, but is not
+limited to:
+
+* Violent threats or language directed against another person.
+* Discriminatory jokes and language.
+* Posting sexually explicit or violent material.
+* Posting (or threatening to post) other people's personally identifying
+  information ("doxing").
+* Personal insults, especially those using racist or sexist terms.
+* Unwelcome sexual attention.
+* Advocating for, or encouraging, any of the above behavior.
+* Repeated harassment of others. In general, if someone asks you to stop, then
+  stop.
+
+## When we disagree, try to understand why
+
+Disagreements, both social and technical, happen all the time and JS Foundation
+projects are no exception. It is important that we resolve disagreements and
+differing views constructively. Remember that we're different. The strength of
+the JS Foundation comes from its varied community, people from a wide range of
+backgrounds. Different people have different perspectives on issues. Being
+unable to understand why someone holds a viewpoint doesn't mean that they're
+wrong. Don't forget that it is human to err and blaming each other doesn't get
+us anywhere. Instead, focus on helping to resolve issues and learning from
+mistakes.
+
+Original text courtesy of the [Speak Up! project](https://web.archive.org/web/20141205224353/http://speakup.io:80/coc.html)
+and [Django Project](https://www.djangoproject.com/conduct/).
+
+All content on this page is licensed under a [Creative Commons Attribution](https://creativecommons.org/licenses/by/3.0/)
+license. ![Creative Commons Attribution 3.0](https://licensebuttons.net/l/by/3.0/88x31.png)
diff --git a/docs/about/CONTRIBUTORS.md b/docs/about/CONTRIBUTORS.md
@@ -1,9 +1,3 @@
----
-title: Contributors | sonar
-tocTitle: contributors
-category: about
-permalink: about/contributors.html
----
 # Contributors
 
 * [Stephanie (Stimac) Drescher ![image](https://avatars1.githubusercontent.com/u/18073131?v=3&s=100)](https://github.com/ststimac)

diff --git a/docs/about/FAQ.md b/docs/about/FAQ.md
@@ -1,9 +1,3 @@
----
-title: Frequently asked questions | sonar
-tocTitle: faq
-category: about
-permalink: about/faq.html
----
 <!-- markdownlint-disable MD026 -->
 
 # FAQ
@@ -41,7 +35,7 @@ difficulty level. Also don't hesitate to ask for help.
 
 ## What browsers are supported?
 
-sonar currently supports [JSDOM](https://github.com/tmpvar/jsdom), Chrome, and Edge 15.
+sonar currently supports [jsdom](https://github.com/tmpvar/jsdom), Chrome, and Edge 15.
 We hope to add support for Firefox soon. If your favorite browser is not
 supported you can always
 [develop a collector](/docs/developer-guide/collectors/index.md) for it!
@@ -53,7 +47,7 @@ Editor plugins are not yet available, but it is high in our priority list.
 ## Is there an online service?
 
 Currently there isn't an online service, but having one is part of our
-priorities for the V1.
+priorities for the v1.
 
 ## What is the logo?
 

diff --git a/docs/about/GOVERNANCE.md b/docs/about/GOVERNANCE.md
@@ -1,9 +1,3 @@
----
-title: Governance | sonar
-tocTitle: governance
-category: about
-permalink: about/governance.html
----
 # Governance
 
 sonar is an open source project that depends on contributions from the

diff --git a/docs/developer-guide/collectors/events.md b/docs/developer-guide/collectors/events.md
@@ -8,6 +8,9 @@ the events common to all `collector`s, with their signature, and the
 * [`fetch::end`](#fetchend)
 * [`fetch::error`](#fetcherror)
 * [`fetch::start`](#fetchstart)
+* [`manifestfetch::end`](#manifestfetchend)
+* [`manifestfetch::error`](#manifestfetcherror)
+* [`manifestfetch::start`](#manifestfetchstart)
 * [`scan::end`](#scanend)
 * [`scan::start`](#scanstart)
 * [`targetfetch::end`](#targetfetchend)
@@ -60,7 +63,7 @@ export interface IFetchEnd {
 
 ## `fetch::error`
 
-Event is emitted **when** the `collector` has encounter a problem
+Event is emitted **when** the `collector` has encountered a problem
 downloading the content of a `resource`.
 
 **Format:**
@@ -94,6 +97,62 @@ export interface IFetchStart {
 
 **Note:** The event is the same for [`targetfetch::start`](#targetfetchstart).
 
+## `manifestfetch::end`
+
+Event is emitted **when** the `collector` has finished downloading
+the web manifest of a page.
+
+**Format:**
+
+```ts
+export interface IFetchEndEvent {
+    /** The element that initiated the request. */
+    element: IAsyncHTMLElement;
+    /** The URL of the target */
+    resource: string;
+    /** The request made to fetch the target. */
+    request: IRequest;
+    /** The response sent while fetching the target. */
+    response: IResponse;
+}
+```
+
+**Note:** The event is the same for [`targetfetch::end`](#targetfetchend).
+
+## `manifestfetch::error`
+
+Event is emitted **when** the `collector` has encountered a problem
+downloading the web manifest.
+
+**Format:**
+
+```ts
+export interface IFetchErrorEvent {
+    /** The URL of the target. */
+    resource: string;
+    /** The error found. */
+    error: any;
+}
+```
+
+**Note:** The event is the same for [`targetfetch::error`](#targetfetcherror).
+
+## `manifestfetch::missing`
+
+Event is emitted **when** the `collector` hasn't found any manifest to
+download.
+
+**Format:**
+
+```ts
+export interface IManifestFetchMissingEvent {
+    /** The URL to download */
+    resource: string;
+}
+```
+
+**Note:** The event is the same for [`targetfetch::start`](#targetfetchstart).
+
 ## `scan::end`
 
 Event is emitted **when** the `collector` has finished sending all
@@ -153,7 +212,7 @@ In this case `element` will be `null`.
 
 ## `targetfetch::error`
 
-Event is emitted **when** the `collector` has encounter a problem
+Event is emitted **when** the `collector` has encountered a problem
 downloading the `target`.
 
 **Format:**
@@ -175,7 +234,7 @@ In this case `element` will be `null`.
 ## `targetfetch::start`
 
 Event is emitted **when** the `collector` is about to start the
-request to fetch the `target`.
+request to fetch the `target`. Redirects are followed if needed.
 
 **Format:**