We use the following public repositories:
https://github.com/datalayer: The Datalayer repositories.
https://github.com/datalayer-contrib: The contributions we make to external projects.
We also use other private repositories. Ask you manager for this.
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”
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
Try to restrict to pure opensource software.
Don’t forget to configure you favorite editors to use 4 spaces instead of tabulations. We use the following languages:
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