COMCIFS dictionary repository layout rules

COMCIFS dictionary repository guidelines

These rules make it easier to develop, maintain and automatically check repository contents, saving everyone time.

Repository administration

Each dictionary has its own repository, which is assigned at least one person with administrative rights. Those persons can then add others with varying levels of privileges. It is recommended to add collaborators freely. There is little risk and a lot of benefit to including many people. Mistakes are easy to undo as everything is version controlled, so lack of experience with Github is not an issue, and the more people available to review and accept changes the better!

Repository layout

Any way of organising the files can be chosen, as long as the following rules are observed:

1. No version numbers in dictionary file names.

Github is a version control system, you do not need to duplicate this functionality. You may "tag" a release if you would like to highlight a version. Also, a lot of the automatic Github file comparison tools are rendered useless if files are renamed with new version numbers each time.

2. All dictionaries are plain text files ending in ".dic".

This allows the automated checking tools to find and check them.

Additional suggestions

These are suggestions only.

1. Have only the dictionary, any imported files and README.md file in the top-level directory

This is for neatness and makes the dictionary easy to find.

2. Avoid storing binary files (such as Word Documents) in the repository.

Changes in binary files are not well tracked by Github version control tools. Instead, consider using plain text Markdown files (how this document is written) which have the added benefit of rendering nicely in the browser.