Skip to content

Latest commit

 

History

History
68 lines (43 loc) · 4.45 KB

CONTRIBUTING.adoc

File metadata and controls

68 lines (43 loc) · 4.45 KB
Raw

How to contribute to Timbuctoo

OMG someone wants to help! That’s so awesome! Quick! give him some hoops to jump through!

Seriously though, this document is intended to let you know what you can expect from us and what we expect from you.

Do you have questions?

Did you find a bug?

Do you want to contribute to the documentation?

Change the docs were needed and submit a Pull Request. You can do so from the github web interface if you like.

Do you want to contribute code?

  • Open a new GitHub pull request that either changes the documentation to describe the new behaviour, or adds new documentation for your new feature. You can use the ./documentation/feature-template

  • Feel free to start coding right away, but we might respond that we won’t merge this PR or that we’ll only merge it if it’s changed a bit.

  • Please read the list of things timbuctoo does and does not do in the README to check if there’s a good chance that we’ll merge your code.

style guide

Commit messages

When committing we try to adhere to http://chris.beams.io/posts/git-commit/

  • Use the imperative mood in the subject line (you should be able to prepend "this commit will" to your subject line. e.g. "This commit will improve the documentation" vs. "This commit will working on doc fixes")

  • Separate subject from body with a blank line

  • Limit the subject line to 50 characters

  • Do not end the subject line with a period

  • Wrap the body at 72 characters

  • Use the body to explain what and why vs. how

  • We have added some conventions of our own

  • When working on a jira issue we tend to start the message with a reference e.g. [TIM-432] Add security layer

  • When a commit is a bugfix or refactoring we start with that. Bugfix. Check if file exists before removing

  • When the fix/refactoring is small you don’t have to add anything other then bugfix/refactoring

Java code

When writing code we try to follow these guidelines:

  • Use a maybe object (preferably java.util.Optional<T>) as the return value of a method when null is a possible value. This way the user of the API is forced to think about how to handle the null case.

  • Use Gremlin as much as possible to execute database queries. Do not use methods that break through the tinkerpop API.

  • Throw an UnsupportedOperationException from any methods that you leave unimplemented. This makes the difference between a method that is expected to do nothing and a method that is not expected to do anything clear. This makes it easier to determine why some calls fail.

  • If you want to create a URI to a timbuctoo endpoint, use the method 'makeUri' in the endpoint you are linking to. This means you have to inject the endpoint you want to link to in your current endpoint.

  • If the method 'makeUri' does not exist create one. Use the makeUri method to create a relative URI of the endpoint and use 'UriHelper.fromResourceUri' to make the URI absolute.

Unit tests

  • If a unit of code leans on another unit for accomplishing its task then that other unit should preferably not be mocked in a unittest.

  • If a unit of code calls another unit of code as a side-effect it should preferably be mocked.

  • When mocking, if the amount of lines needed for the mock becomes "big" then you should take care to keep the "intent" clear. e.g. break it into whitespace separated blocks with comments or extract it to separate methods or builders. If it is hard to mock correctly then you probably should not mock at all but instead use the actual implementation.

  • Give your tests a name that is useful from the perspective of the API. i.e. It should describe what the user of the unit can expect or should take into account.

  • You should only write tests for the code that is used and defined. Code that is handles logical impossibilities (such as the default case in a switch statement that handles all branches of an enum) or code that handles a failed invariant (such as a broken foreign key) should still be written, but not have tests added to source control.

💕 Thank you! 💕