Gallery

Gallery.

Guidelines

Guidelines

Repositories

We use the following public repositories:

We also use other private repositories. Ask you manager for this.

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.md Usage

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

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

It could contain the following information.

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

Open Source is Preferred

Try to restrict to pure opensource software.

Coding Style

Don’t forget to configure you favorite editors to use 4 spaces instead of tabulations. We use the following languages:

Commits

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):

CODE SECTION: 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