# Contributing

[Bug](#found-a-bug) | [Pull Request](#pull-request) | [Documentation](#documentation)

## Question or Problem?

If you have a question on how to use 3D.io or the products, please direct these to [Stack Overflow](https://stackoverflow.com/questions/tagged/aframe%20and%203d.io%20or%20archilogic). It's the best way to reach us.

In case you find something that is a bug, read on :-)

## Found a bug?

Please provide the following information:
* **How to Reproduce**
  Describe in a few steps the actions to make the bug appear.
  Provide a code snippet or a URL of with an example ([App Creator](https://appcreator.3d.io) or [glitch](https://glitch.com/))

* **Actual Result**
  Describe the bug in a few words.
  Attach a screen shot of the graphical or console error if these are relevant.

* **Expected Result**
  Describe what you would expect to happen.

* **Notes**
  Share relevant details to your setup
  Which OS is affected?
  Which Browsers are affected?
  What devices are affected?
  What build are you using?

## Missing something?

If you think something's missing, we'd love to have your input!

### Minor change (e.g. doc fix, typo, wording)

For minor changes, please craft and submit a pull request with the necessary changes against the `master` branch.

### Major change (e.g. structure, features)

For major changes we'd love to discuss the proposed changes as a Github issue in this repository, so we can better coordinate our efforts, avoid duplication of work, and help you contribute to the project successfully and smoothly.

## Pull Request
This guide should help to create and standardise the process of creating,
reviewing and merging a pull request.

### Style
Give a general quick overview about the pull request, and provide links 
to in-depth information about the design and implementation process.

    Scope & Features:
    - What is the pull request for, which features does it implement
    - Why should this feature be included
    
    Design:
    - How was the code designed
    - Reference the Github Issue / Github Project associated
    
    How to use:
    - How does the new feature work
    - How do the changes affect users
    
    How to test:
    - How has this feature been tested?
    
    Notes:
    - Additional information for the reviewer
    
### Review process
* Assign yourself as the assignee
* Choose a reviewer for the pull request, usually there is a lead in the suggestions.

**Role of the Reviewer**
* Approve changes in code snippets and give final permission to merge
* Never change the code directly, let the **assignee** learn from your feedback!
* Test functionality
* Review code style
* Suggest code edit directly in the **files changed**
* Questions:
  * Is this change useful to the majority of users
  
**Role of the Assignee**
* Conduct all the changes required by the Reviewer
* Provide insights in the design and decision making
* (...)

**Iterate**
* Iterate until every question & problem is resolved

**Don't be evil!**

### The Merge
(WIP)


## Documentation

### Wording
* User centric
  * Imagine you are speaking to a beginner, helping him to achieve a simple useful task.
  * Prefer popular terms over technicaly correct ones
  * Titles should be achievements (i.e. "Upload files")
* Short sentences
* Focused and precise
  * Explain one thing at a time.
  * Do not explain related topics but provide a link to the page where they are being explained. 
* Add links whenever possible. 

### Examples
* Every example should be executable without modification
  * Do not use fake ids (i.e. "12345")
  * Avoid template-like placeholders (i.e. "/<your-folder>/index.html")
* Isomorphic code should be presented in generic examples.
* Examples for specific environments should be declared as such explicitly.
* Distinguish secret from publishable keys and always explicitly declare them as such.