Contribute

You are welcome to contribute on this project as a User or as a Developer hacking on the base source code available in our GitHub repositories.

We use public repositories hosted in the Datalayer GitHub account.

  • datalayer/datalayer repository contains the source code to run the REST server endpoints. The main branch is master.
  • datalayer-contrib account hosts external project that Datalayer uses and may contribute to.

If you have to start from scratch, just follow our quick start install guide.

We are looking forward to your feedbacks on the current version and inputs on our release plan to fit your needs, especially in terms of applications, storage systems and cloud support you want to use.

Documentation

Documentation is important to share knowledge and make life easy. Read the guidelines to write better documentation.

Repository Structure

We don't have a fixed structure as it really depends on the goal (content) of the repository and also on the people that are contributing to it.

Just rememember that your are not alone to use that repository, and that other will come after you to support and further work on it. As such, please be open and take into account the other expectations and ideas to let the structure evolve.

Just agree and ensure to have a uniform way to name the folders and files (e.g. if you use "20140305-report.txt" and not "20140305_Report.txt", apply this everywhere in the repository).

For documents to be sent to external parties, rely on the following convention: "PartyName ProjectName RefNumber VersionNumber LastModifiedDate.ext"

README

We love README.md in the repositories because they are short and easy to read.

Follow the standard-readme specifications.

The README.md is more a teaser and should point to a more complete web site.

It could contain the following information.

  • Repository objective.
  • Prerequiste (on technology and any other level).
  • Setup.
  • Configuration.
  • Usage.
  • License.

Try to be concise and split if needed (hopefully not...).

Finish by a nice invitation such as.

Looking for help? Sure there are plenty of things to do, get in touch with @DatalayerIO

Changes

Implement your changes in a separated branch and ensure you have proper unit tests to cover new features.

Commit and push your changes. Please open a pull request to enhance or fix the content of this repository so another developer can review and merge your changes.

For tiny fixes like typo..., just commit and push directly in the master branch directly.

Commit Messages

We encourage the use of Semantic commit messages.

Use a rigid commit message format, and it makes me a better programmer.

feat: add hat wobble
^--^  ^------------^
|     |
|     +-> Summary in present tense.
|
+-------> Type: chore, docs, feat, fix, refactor, style, or test.

More Examples:

chore: add Oyster build script
docs: explain hat wobble
feat: add beta sequence
fix: remove broken confirmation message
refactor: share logic between 4d3d3d3 and flarhgunnstow
style: convert tabs to spaces

The reasons for these conventions:

  • Automatic generating of the changelog.
  • Simple navigation through git history (eg. ignoring style changes).

In order to have readable git logs, we follow some simple rules.

Commits shouldn't contain multiple unrelated changes; try and make piecemeal changes if you can, to make it easier to review and merge. In particular, don't commit style/whitespace changes and functionality changes in a single commit.

If you change shared common code, then (while not necessarily in the same commit, due to the above guideline!) you should also make at least a best-effort attempt to make sure all of the code stays working.

The rules on commit messages are the following (they're standard to git):

feat: Short (50 chars or less) summary of changes

More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so.  In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body.  The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.

Write your commit message in the present tense: "Fix bug" and not "Fixed
bug."  This convention matches up with commit messages generated by
commands like git merge and git revert.

Further paragraphs come after blank lines.

- Bullet points are okay, too

- Typically a hyphen or asterisk is used for the bullet, preceded by a
 single space, with blank lines in between, but conventions vary here

- Use a hanging indent

Particularly critical is the first line: This first line is used in short log format, providing the section of the repo you are working on or whatever lets decide quickly should reviewers look deeply into commit or skip.

So if your commit is about the doc, please, write DOC as a prefix. Or if you change the readme, use README. The prefix is not about really what you've done but more where you've done. As a bad example, something like this where the commit is about a change in the readme:

scala: Point to scala ide.

should be more like

readme: Point to scala ide.

Commit Message Specification

<type>(<scope>): <subject>

Message Subject (first line)

First line cannot be longer than 70 characters, second line is always blank and other lines should be wrapped at 80 characters.

Allowed values:

feat: new feature
fix: bug fix
docs: changes to documentation
style: formatting, missing semi colons, etc; no code change
refactor: refactoring production code
test: adding missing tests, refactoring tests; no production code change
chore: updating grunt tasks etc; no production code change

Example values:

init
runner
watcher
config
web-server
proxy
etc.

The can be empty (eg. if the change is a global or difficult to assign to a single component), in which case the parentheses are omitted.

Message Body

Uses the imperative, present tense: “change” not “changed” nor “changes”.

Includes motivation for the change and contrasts with previous behavior.

For more info about message body, see:

http://365git.tumblr.com/post/3308646748/writing-git-commit-messages

http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

Referencing issues

Closed issues should be listed on a separate line in the footer prefixed with "Closes" keyword like this:

Closes #234

or in case of multiple issues:

Closes #123, #245, #992

Breaking changes

All breaking changes have to be mentioned in footer with the description of the change, justification and migration notes.

BREAKING CHANGE:

port-runner command line option has changed to runner-port, so that it is consistent with the configuration file syntax.

To migrate your project, change all the commands, where you use --port-runner to --runner-port.

Open Source is Preferred

Try to restrict to software and libraries with pure opensource licenses.

Coding Style

Don't forget to configure you favorite editors to use 4 spaces instead of tabulations.

We use the following languages:

  • Python (Code Style to be defined)
  • R (Code Style)
  • Bash (code style to be defined)
  • Scala (Code Style to be defined)
  • Java (Code Style to be defined)

results matching ""

    No results matching ""