Skip to content

Commit

Permalink
Docs: Reorganize contributor guide
Browse files Browse the repository at this point in the history 
Fix #781
Close #784
  • Loading branch information
@molant
molant committed Jan 31, 2018
1 parent 2134b88 commit 129ec11
Show file tree
Hide file tree
Showing 16 changed files with 746 additions and 678 deletions.
4 changes: 2 additions & 2 deletions README.md
View file
Expand Up @@ -56,10 +56,10 @@ the [local version](./docs/contributor-guide/index.md)).

The following are meant only if you are working on `sonarwhal`’s codebase:

* `npm run site <url>` will analyze the website with the current
* `npm run sonarwhal <url>` will analyze the website with the current
configuration and using the latest build available in the `dist`
directory.
* `npm run site -- --debug <url>` same as above, but will show all
* `npm run sonarwhal -- --debug <url>` same as above, but will show all
the debug information.
* `npm run lint` will lint the code.
* `npm run watch` will start watchmode. This is the recommended task
Expand Down
60 changes: 60 additions & 0 deletions docs/contributor-guide/getting-started/architecture.md
View file
@@ -0,0 +1,60 @@
# Architecture

`sonarwhal` was designed with extensibility in mind. At a high level, this is
the project's architecture:

![sonarwhal's architecture](../architecture.png)

The main piece is `sonarwhal`. It's an object that extends from `EventEmitter`.
This means that the communication between all the different parts is going to
be done mostly via [`event`s][events]. The other pieces are:

* `rule`: Is a group of related tests that are run on a resource (HTML,
document, image, request, etc.). E.g.: Verify that the HTML document has a
valid language declared.
[Learn how to develop a `rule`][new rule].
* `connector`: Is the way in which `sonarwhal` obtains information about the
DOM, network information, resources, etc. The underlying technique (debugging
protocol, web driver, etc.) to access this data does not matter to the rest
of the system.
[Learn how to develop a `connector`][new connector].
* `formatter`: Transforms the results into something useful to the user. It
could be as simple as printing out the results to the command line, or
something more complex like creating an HTML report.
[Learn how to developer a `formatter`][new formatter].
* `parser`: Understands a particular resource type (e.g.: JavaScript,
stylesheet, webmanifest, etc.), parses it, and emits related event(s) so
`rule`s can take action on them.
[Learn how to develop a `parser`][new parser].

When a user invokes `sonarwhal https://example.com` basically what happens is
this:

1. The `CLI` creates a new `sonarwhal`
1. `sonarwhal` loads the configuration in `.sonarwhalrc` or
`package.json` and the associated resources
1. `CLI` then calls the `analyze` method.
1. `sonarwhal` then calls the `collect` method of the configured `connector`.
1. The `connector` will navigate to the `URL` traverse the HTML, and send
`event`s related to this and the resource loading process.
1. If a `parser` has subscribed to one of the emitted `event`s, it will parse
that resource and `emit` new `event`s.
1. `rule`s can subscribe to any `event` no matter where it's comming from
(`connector` or `parser`). If they find an issue, it will be reported via the
`report` method.
1. Once `sonarwhal` has finished analyzing the website, the results are returned
to `CLI` that will print them using the configured `formatter`(s).

Any developer can create their own `rule`s, `connector`s, `parser`s
and/or `formatter`s, and use them without having to do a pull request to
the main project and distribute them as [`npm`][npm] packages.

<!-- Link labels: -->

[events]: ./events.md
[new connector]: ../how-to/connector.md
[new formatter]:../how-to/formatter.md
[new parser]: ../how-to/parser.md
[new rule]: ../how-to/rule.md
[npm]: https://www.npmjs.com/
[typescript]: https://www.typescriptlang.org/
Binary file added docs/contributor-guide/getting-started/architecture.png
View file
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
34 changes: 9 additions & 25 deletions ...tributor-guide/development-environment.md → ...etting-started/development-environment.md
View file
@@ -1,30 +1,22 @@
# Development Environment
# Development environment

This is a step-by-step guide to setting up a local development
environment that will let you contribute back to the project.

1. [Install Node.js](#step-1)
2. [Fork and checkout your own sonarwhal repository](#step-2)
3. [Add the upstream source](#step-3)
4. [Run the tests](#step-4)
1. [Install Node.js](#step-1-install-nodejs)
2. [Fork and checkout your own sonarwhal repository](#step-2-fork-and-checkout-your-own-sonarwhal-repository)
3. [Add the upstream source](#step-3-add-the-upstream-source)
4. [Run the tests](#step-4-run-the-tests)

<!-- markdownlint-disable MD033 -->

## Step 1: Install Node.js <a name="step-1"></a>

<!-- markdownlint-enable MD033 -->
## Step 1: Install Node.js

Go to [`nodejs.org`][nodejs] to download and install the latest stable
version of `Node.js` for your operating system.

**Note:** By installing `Node.js` you will also get [`npm`][npm], which
we will use to install packages that `sonarwhal` depends on.

<!-- markdownlint-disable MD033 -->

## Step 2: Fork and checkout your own sonarwhal repository <a name="step-2"></a>

<!-- markdownlint-enable MD033 -->
## Step 2: Fork and checkout your own sonarwhal repository

Go to <https://github.com/sonarwhal/sonarwhal> and click the `Fork` button.
Follow the [GitHub documentation][github fork docs] for forking and cloning.
Expand All @@ -50,11 +42,7 @@ npm install
You must be connected to the Internet for this step to work. You’ll
see a lot of utilities being downloaded.

<!-- markdownlint-disable MD033 -->

## Step 3: Add the upstream source <a name="step-3"></a>

<!-- markdownlint-enable MD033 -->
## Step 3: Add the upstream source

The *upstream source* is the main `sonarwhal` repository that active
development happens on. While you won’t have push access to upstream,
Expand All @@ -70,11 +58,7 @@ git remote add upstream git@github.com:sonarwhal/sonarwhal.git

Now, the remote `upstream` points to the upstream source.

<!-- markdownlint-disable MD033 -->

## Step 4: Run the tests <a name="step-4"></a>

<!-- markdownlint-enable MD033 -->
## Step 4: Run the tests

Running the tests is the best way to ensure you have correctly set up
your development environment. Make sure you’re in the `sonarwhal`
Expand Down
25 changes: 21 additions & 4 deletions docs/contributor-guide/connectors/events.md → ...ntributor-guide/getting-started/events.md
View file
@@ -1,8 +1,9 @@
# Events

`connector`s communicate via events. The following is a list of all
the events common to all `connector`s, with their signature, and the
`interface` they implement.
Information is shared internally via `event`s. `connector`s and `parser`s can
create them, while `parser`s and `rule`s consume them.
The following is a list of all the events common to all `connector`s, with
their signature, and the `interface` they implement.

* [`element::<element-type>`](#elementelement-type)
* [`fetch::end`](#fetchend)
Expand Down Expand Up @@ -172,6 +173,22 @@ export interface IManifestFetchMissing {
}
```

## `parse::javascript`

Event is emitted **when** the `JavaScript parser` has finished parsing a
JavaScript resource (a file or a `<script>` tag).

**Format:**

```ts
export interface IScriptParse {
/** The URL of the resource. */
resource: string;
/** The source code parsed */
sourceCode: any;
}
```

## `scan::end`

Event is emitted **when** the `connector` has finished sending all
Expand Down Expand Up @@ -313,7 +330,7 @@ export interface ITraverseStart {

## `traverse::up`

Event is emitted **when** the `connector` has finsihed visting the
Event is emitted **when** the `connector` has finsihed visiting the
children of a node and goes to the next one. `element` is the parent
node that was traversed.

Expand Down
62 changes: 17 additions & 45 deletions ...butor-guide/contributing/pull-requests.md → ...or-guide/getting-started/pull-requests.md
View file
@@ -1,4 +1,4 @@
# Pull Requests
# Pull requests

Contributing code to `sonarwhal` is done using pull requests. This is
the fastest way for us to evaluate your code and to merge it into
Expand All @@ -22,7 +22,7 @@ and we will assign it to you.
For bug fixes, documentation changes, and other small changes, there is
no need to create an issue, and you can just make the pull request.

## Getting Started
## Getting started

If you’d like to work on a pull request, and you’ve never submitted
code before, follow these steps:
Expand All @@ -32,24 +32,20 @@ code before, follow these steps:

After that, you’re ready to start working on code.

## Working with Code
## Working with code

The process of submitting a pull request is fairly straightforward,
and generally follows the same pattern each time:

1. [Create a new branch](#step-1)
2. [Make your changes](#step-2)
3. [Rebase onto upstream](#step-3)
4. [Run the tests](#step-4)
5. [Double check your submission](#step-5)
6. [Push your changes](#step-6)
7. [Submit the pull request](#step-7)
1. [Create a new branch](#step-1-create-a-new-branch)
2. [Make your changes](#step-2-make-your-changes)
3. [Rebase onto upstream](#step-3-rebase-onto-upstream)
4. [Run the tests](#step-4-run-the-tests)
5. [Double check your submission](#step-5-double-check-your-submission)
6. [Push your changes](#step-6-push-your-changes)
7. [Submit the pull request](#step-7-submit-the-pull-request)

<!-- markdownlint-disable MD033 -->

### Step 1: Create a new branch <a name="step-1"></a>

<!-- markdownlint-enable MD033 -->
### Step 1: Create a new branch

The first step to sending a pull request is to create a new branch
in your `sonarwhal` fork. Give the branch a descriptive name that best
Expand All @@ -64,11 +60,7 @@ You should do all of your development for the issue in this branch.
**Note:** Do not combine fixes for multiple issues into one branch.
Use a separate branch for each issue you’re working on.

<!-- markdownlint-disable MD033 -->

### Step 2: Make your changes <a name="step-2"></a>

<!-- markdownlint-enable MD033 -->
### Step 2: Make your changes

Make the changes to the code, documentation, and tests, and once you
are done, commit the changes to your branch:
Expand Down Expand Up @@ -148,11 +140,7 @@ characters.
the messages in our automatic release process (determining the new
version number, updating the changelog, etc.).

<!-- markdownlint-disable MD033 -->

### Step 3: Rebase onto upstream <a name="step-3"></a>

<!-- markdownlint-enable MD033 -->
### Step 3: Rebase onto upstream

Before you send the pull request, be sure to rebase onto the
[upstream source](../development-environment.md). This ensures your
Expand All @@ -163,11 +151,7 @@ git fetch upstream
git rebase upstream/master
```

<!-- markdownlint-disable MD033 -->

### Step 4: Run the tests <a name="step-4"></a>

<!-- markdownlint-enable MD033 -->
### Step 4: Run the tests

After rebasing, be sure to run all of the tests once again to make
sure nothing broke:
Expand All @@ -178,11 +162,7 @@ npm test

If there are any failing tests, update your code until all tests pass.

<!-- markdownlint-disable MD033 -->

### Step 5: Double check your submission <a name="step-5"></a>

<!-- markdownlint-enable MD033 -->
### Step 5: Double check your submission

With your code ready to go, this is a good time to double-check your
submission to make sure it follows our conventions. Here are the things
Expand All @@ -197,11 +177,7 @@ to check:
* All changes must be accompanied by documentation and tests, even if
the feature you’re working on previously had no documentation or tests.

<!-- markdownlint-disable MD033 -->

### Step 6: Push your changes <a name="step-6"></a>

<!-- markdownlint-enable MD033 -->
### Step 6: Push your changes

Next, push your changes to your fork:

Expand All @@ -216,11 +192,7 @@ push instead:
git push -f origin fix-1234
```

<!-- markdownlint-disable MD033 -->

### Step 7: Send the pull request <a name="step-7"></a>

<!-- markdownlint-enable MD033 -->
### Step 7: Send the pull request

Now you’re ready to send the pull request. Go to your `sonarwhal` fork
and then follow the [GitHub documentation][github pr docs] on how to
Expand Down
12 changes: 6 additions & 6 deletions ...de/rules/tutorial-create-external-rule.md → ...ibutor-guide/guides/create-custom-rule.md
View file
@@ -1,4 +1,4 @@
# Tutorial of creating an external rule
# Create a custom rule step-by-step

Imagine that we have a new change in the sonarwhal website - we’d like
to add a footer containing the copyright information `(c) sonarwhal` and
Expand All @@ -19,16 +19,16 @@ rule subscribes to `fetch::end`, it means this rule will run each time the
connector finishes downloading a resource file. There are two types of rules:

* `core rules` which are shipped with sonarwhal, geared towards general public use
* `external rules` which are specific to a domain or a particular use case, thus
* `custom rules` which are specific to a domain or a particular use case, thus
published independently

Because our need of checking the footer is unique, we’ll add it as an external
Because our need of checking the footer is unique, we’ll add it as a custom
rule instead of doing a pull request to sonarwhal’s core rules.

## What is it like to start a new external rule?
## What is it like to start a new custom rule?

The recommended way to create a new rule is to use the `—-new-rule` parameter in
CLI. Support for bootstrapping external rules has shipped in sonarwhal since
CLI. Support for bootstrapping custom rules has shipped in sonarwhal since
v0.20.1. sonarwhal can be installed globally to have access to the sonarwhal
command directly. You can also install it locally and run it via npm scripts or
using the `npx` command.
Expand All @@ -38,7 +38,7 @@ npm install -g --engine-strict sonarwhal
```

Afterwards, we navigated to the folder where we’d like to put the rule project,
and then run the command to start a new external rule:
and then run the command to start a new custom rule:

```bash
sonarwhal --new-rule
Expand Down

0 comments on commit 129ec11

Please sign in to comment.