Skip to content

Latest commit

 

History

History
116 lines (84 loc) · 3.8 KB

CONTRIBUTING.md

File metadata and controls

116 lines (84 loc) · 3.8 KB
Raw

Contributing

Bug | Pull Request | Documentation

Question or Problem?

If you have a question on how to use 3D.io or the products, please direct these to Stack Overflow. 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 or glitch)

  • 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. "//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.