Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Amend Codeblocks, add highlight and format markdown #389

Merged
merged 4 commits into from
Mar 27, 2019
Merged

Amend Codeblocks, add highlight and format markdown #389

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
9a9b7c1
Amend Codeblocks, add highlight and format markdown
jason-fox Mar 26, 2019
fb9c400
First round of fixes
jason-fox Mar 26, 2019
811dbf4
Remove superfences and codehilite
jason-fox Mar 26, 2019
5014013
Remove split
jason-fox Mar 26, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
187 changes: 84 additions & 103 deletions docs/CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,126 +2,103 @@

Looking to contribute something to WireCloud? **Here's how you can help.**

Please take a moment to review this document in order to make the contribution
process easy and effective for everyone involved.
Please take a moment to review this document in order to make the contribution process easy and effective for everyone
involved.

Following these guidelines helps to communicate that you respect the time of
the developers managing and developing this open source project. In return,
they should reciprocate that respect in addressing your issue or assessing
patches and features.
Following these guidelines helps to communicate that you respect the time of the developers managing and developing this
open source project. In return, they should reciprocate that respect in addressing your issue or assessing patches and
features.

**Contents**

- [Using the issue tracker](#using-the-issue-tracker)
- [Bug reports](#bug-reports)
- [Feature requests](#feature-requests)
- [Contributing code](#contributing-code)
- [Code Guidelines](#code-guidelines)

- [Using the issue tracker](#using-the-issue-tracker)
- [Bug reports](#bug-reports)
- [Feature requests](#feature-requests)
- [Contributing code](#contributing-code)
- [Code Guidelines](#code-guidelines)

## Using the issue tracker

The [issue tracker](https://github.com/Wirecloud/wirecloud/issues) is
the preferred channel for [bug reports](#bug-reports) and
[features requests](#feature-requests), but please respect the following
restrictions:

* Please **do not** use the issue tracker for personal support requests. Stack
Overflow ([`fiware-wirecloud`](http://stackoverflow.com/questions/tagged/fiware-wirecloud)
tag) is a better place to get help.
The [issue tracker](https://github.com/Wirecloud/wirecloud/issues) is the preferred channel for
[bug reports](#bug-reports) and [features requests](#feature-requests), but please respect the following restrictions:

* Please **do not** derail or troll issues. Keep the discussion on topic and
respect the opinions of others.
- Please **do not** use the issue tracker for personal support requests. Stack Overflow
([`fiware-wirecloud`](http://stackoverflow.com/questions/tagged/fiware-wirecloud) tag) is a better place to get
help.

- Please **do not** derail or troll issues. Keep the discussion on topic and respect the opinions of others.

## Bug reports

A bug is a _demonstrable problem_ that is caused by the code in the repository.
Good bug reports are extremely helpful, so thanks!
A bug is a _demonstrable problem_ that is caused by the code in the repository. Good bug reports are extremely helpful,
so thanks!

Guidelines for bug reports:

1. **Use the GitHub issue search** — check if the issue has already been
reported.

2. **Check if the issue has been fixed** — try to reproduce it using the
latest `master` or development branch in the repository.
1. **Use the GitHub issue search** — check if the issue has already been reported.

3. **Isolate the problem** — ideally create a [reduced test
case](http://css-tricks.com/6263-reduced-test-cases/) and a live example.
2. **Check if the issue has been fixed** — try to reproduce it using the latest `master` or development branch in
the repository.

3. **Isolate the problem** — ideally create a [reduced test case](http://css-tricks.com/6263-reduced-test-cases/)
and a live example.

A good bug report shouldn't leave others needing to chase you up for more
information. Please try to be as detailed as possible in your report. What is
your environment? What steps will reproduce the issue? What browser(s) and OS
experience the problem? Do other browsers show the bug differently? What
would you expect to be the outcome? All these details will help people to fix
any potential bugs.
A good bug report shouldn't leave others needing to chase you up for more information. Please try to be as detailed as
possible in your report. What is your environment? What steps will reproduce the issue? What browser(s) and OS
experience the problem? Do other browsers show the bug differently? What would you expect to be the outcome? All these
details will help people to fix any potential bugs.

Example:

> Short and descriptive example bug report title
>
> A summary of the issue and the browser/OS environment in which it occurs. If
> suitable, include the steps required to reproduce the bug.
> A summary of the issue and the browser/OS environment in which it occurs. If suitable, include the steps required to
> reproduce the bug.
>
> 1. This is the first step
> 2. This is the second step
> 3. Further steps, etc.
>
> `<url>` - a link to the reduced test case
>
> Any other information you want to share that is relevant to the issue being
> reported. This might include the lines of code that you have identified as
> causing the bug, and potential solutions (and your opinions on their
> merits).

> Any other information you want to share that is relevant to the issue being reported. This might include the lines of
> code that you have identified as causing the bug, and potential solutions (and your opinions on their merits).

## Feature requests

Feature requests are welcome. But take a moment to find out whether your idea
fits with the scope and aims of the project. It's up to *you* to make a strong
case to convince the project's developers of the merits of this feature. Please
provide as much detail and context as possible.

Feature requests are welcome. But take a moment to find out whether your idea fits with the scope and aims of the
project. It's up to _you_ to make a strong case to convince the project's developers of the merits of this feature.
Please provide as much detail and context as possible.

## Contributing code

If you're ready to take the plunge & contribute back some code/docs, the process
should look like:

- Fork the project on GitHub into your own account.
- Clone your copy of WireCloud.
- Make a new branch in git & commit your changes there.
- Push your new branch up to GitHub.
- Again, ensure there isn't already an issue or pull request out there on it.
If there is & you feel you have a better fix, please take note of the issue
number & mention it in your pull request.
- Create a new pull request (based on your branch), including what the
problem/feature is, versions of your software & referencing any related
issues/pull requests.

In order to be merged into WireCloud, contributions should follow the following
recommendation as much as possible:

- A solid patch that:
- is clear.
- works across all supported versions of Python/Django (take a look to the
If you're ready to take the plunge & contribute back some code/docs, the process should look like:

- Fork the project on GitHub into your own account.
- Clone your copy of WireCloud.
- Make a new branch in git & commit your changes there.
- Push your new branch up to GitHub.
- Again, ensure there isn't already an issue or pull request out there on it. If there is & you feel you have a better
fix, please take note of the issue number & mention it in your pull request.
- Create a new pull request (based on your branch), including what the problem/feature is, versions of your software &
referencing any related issues/pull requests.

In order to be merged into WireCloud, contributions should follow the following recommendation as much as possible:

- A solid patch that:
- is clear.
- works across all supported versions of Python/Django (take a look to the
[documentation about testing](development/platform/testing.md))
- follows the [Code guidelines](#code-guidelines).
- comments included as needed.
- A test case that demonstrates the previous flaw that now passes with the
included patch.
- If it adds/changes a public API, it must also include documentation for those
changes.
- follows the [Code guidelines](#code-guidelines).
- comments included as needed.
- A test case that demonstrates the previous flaw that now passes with the included patch.
- If it adds/changes a public API, it must also include documentation for those changes.

You can manually test your changes by running WireCloud directly from the
working copy source code repository. The provided `settings.py` file will use
a shared security key and a basic configuration (e.g. using `sqlite3`) so it is
not ready for a production environments, but can be used for simple manual
tests. Those are the steps to be followed:
You can manually test your changes by running WireCloud directly from the working copy source code repository. The
provided `settings.py` file will use a shared security key and a basic configuration (e.g. using `sqlite3`) so it is not
ready for a production environments, but can be used for simple manual tests. Those are the steps to be followed:

```shell
```bash
#
# Download your WireCloud repository
#
Expand Down Expand Up @@ -181,38 +158,42 @@ python manage.py runserver
#
```


### Code guidelines

#### Python

- Follow the [PEP 8 style rules](https://www.python.org/dev/peps/pep-0008/)
- Use [`flake8`](http://flake8.pycqa.org/en/latest/) (or alternatively, `pep8`
and `pyflakes` in combination)
- Follow the [PEP 8 style rules](https://www.python.org/dev/peps/pep-0008/)
- Use [`flake8`](http://flake8.pycqa.org/en/latest/) (or alternatively, `pep8` and `pyflakes` in combination)

#### JavaScript

- Four spaces for indentation, never tabs.
- strict mode.
- "Attractive".
- Use [`eslint`](http://eslint.org/) (there is a `.eslintrc` file on the source
code of WireCloud ;-).
- Four spaces for indentation, never tabs.
- strict mode.
- "Attractive".
- Use [`eslint`](http://eslint.org/) (there is a `.eslintrc` file on the source code of WireCloud ;-).

#### HTML

- Four spaces for indentation, never tabs.
- Double quotes only, never single quotes.
- Always use proper indentation.
- Use tags and elements appropriate for an XHTML5 doctype (e.g., self-closing tags).
- Four spaces for indentation, never tabs.
- Double quotes only, never single quotes.
- Always use proper indentation.
- Use tags and elements appropriate for an XHTML5 doctype (e.g., self-closing tags).

#### SCSS

- Multiple-line approach (one property and value per line).
- Always a space after a property's colon (e.g., `display: block;` and not `display:block;`).
- End all lines with a semi-colon.
- Attribute selectors, like `input[type="text"]` should always wrap the attribute's value in double quotes, for consistency and safety (see this [blog post on unquoted attribute values](http://mathiasbynens.be/notes/unquoted-attribute-values) that can lead to XSS attacks).
- Attribute selectors should only be used where absolutely necessary (e.g., form controls) and should be avoided on custom components for performance and explicitness.
- Series of classes for a component should include a base class (e.g., `.component`) and use the base class as a prefix for modifier and sub-components (e.g., `.component-lg`).
- Avoid inheritance and over nesting—use single, explicit classes whenever possible.
- When feasible, default color palettes should comply with [WCAG color contrast guidelines](http://www.w3.org/TR/WCAG20/#visual-audio-contrast).
- Except in rare cases, don't remove default `:focus` styles (via e.g. `outline: none;`) without providing alternative styles. See [this A11Y Project post](http://a11yproject.com/posts/never-remove-css-outlines/) for more details.
- Multiple-line approach (one property and value per line).
- Always a space after a property's colon (e.g., `display: block;` and not `display:block;`).
- End all lines with a semi-colon.
- Attribute selectors, like `input[type="text"]` should always wrap the attribute's value in double quotes, for
consistency and safety (see this
[blog post on unquoted attribute values](http://mathiasbynens.be/notes/unquoted-attribute-values) that can lead to
XSS attacks).
- Attribute selectors should only be used where absolutely necessary (e.g., form controls) and should be avoided on
custom components for performance and explicitness.
- Series of classes for a component should include a base class (e.g., `.component`) and use the base class as a
prefix for modifier and sub-components (e.g., `.component-lg`).
- Avoid inheritance and over nesting—use single, explicit classes whenever possible.
- When feasible, default color palettes should comply with
[WCAG color contrast guidelines](http://www.w3.org/TR/WCAG20/#visual-audio-contrast).
- Except in rare cases, don't remove default `:focus` styles (via e.g. `outline: none;`) without providing alternative
styles. See [this A11Y Project post](http://a11yproject.com/posts/never-remove-css-outlines/) for more details.
Loading