Skip to content

Latest commit

 

History

History
110 lines (89 loc) · 4.86 KB

CONTRIBUTING.md

File metadata and controls

110 lines (89 loc) · 4.86 KB

Introduction

Thanks for your interest in OpenSolid! Currently, the best way to contribute is simply to open a new issue for any new features you're interested in or any bugs you notice (including things like misleading or confusing documentation - documentation issues are just as important as code issues!). If you're willing to help fix the bug/implement the feature, please mention that in the issue, but it's certainly not a requirement!

In general, I try to follow the Elm guidelines and ask that you try to as well:

  • Be kind.
  • Learn from everyone.
  • Collaboration requires communication.
  • Not every problem should be solved with code.
  • Communication is contribution.
  • Understand the problem.
  • Explore all possible solutions.
  • Pick one.
  • Simplicity is not just for beginners.
  • It's better to do it right than to do it right now.
  • It's not done until the docs are great.
  • Take responsibility for user experiences.
  • Make impossible states impossible.
  • There are worse things than being explicit...

Contributing changes

If you are interested in contributing changes to OpenSolid, please fork this repository, make a new branch in your fork, commit your changes to that branch and then make a pull request from that branch (although please open an issue first for major contributions before writing too much code, so we can discuss different potential approaches). As part of your pull request, make sure that you add yourself to the AUTHORS file! Definitely reach out on the Elm Slack if you have questions (I'm ianmackenzie).

Writing code

When writing your code, try to follow existing code style as much as possible - in particular, this means:

  • Use elm-format to format your code. I currently use elm-format version 0.7.0-exp.
  • Wrap code (mostly) to 80 columns (type annotations and string literals can be longer if you want).

Don't worry too much about writing documentation - small fixes for things like typos and formatting are certainly welcome, but I would prefer to write the bulk of the documentation myself to ensure a consistent style and tone throughout.

Testing

During development, please run the existing tests periodically to make sure you haven't accidentally broken anything! To run the tests:

  • Run elm package install inside the tests subdirectory
  • Install elm-test by running npm install -g elm-test
  • Run elm-test from the root directory of this repository

If you are working on fixing a bug, please first add a test that catches the bug to the relevant file in the tests subdirectory, then add your fix and verify that the test now passes. If you are adding a new feature, writing tests for your feature is appreciated but not mandatory.

Committing

Git commits should generally be as small and focused as possible, so that they can be reviewed individually. Commit messages should follow the seven rules of a great Git commit message:

  • Separate subject from body with a blank line
  • Limit the subject line to 50 characters
  • Capitalize the subject line
  • Do not end the subject line with a period
  • Use the imperative mood in the subject line
  • Wrap the body at 72 characters
  • Use the body to explain what and why vs. how

Here are some sample commits to use as examples:

Sublime Text configuration

If you happen to use Sublime Text as your editor, here is the (very simple) Sublime Text project file I use for editing OpenSolid code. I create an opensolid directory, place the project file in it, check out all OpenSolid repositories as subdirectories, then open the project file in Sublime Text so I can edit all of my checked-out OpenSolid repositories at once. The resulting directory structure looks like:

opensolid
├── opensolid.sublime-project
├── geometry
│   ├── .git
│   ├── README.md
│   ├── src
│   ├── ...
├── svg
│   ├── .git
│   ├── README.md
│   ├── src
│   ├── ...