Summary
Table of Contents
The following agreed upon conventions are important to ensure consistency across the project.
Most of these conventions are the same as those adopted in other ALAN related projects and repositories, and they are the result of the ALAN IF Development team collaborative editing experience, their learned lessons (and mistakes), and best practices discovered along the way.
Established conventions simplify working across different projects in a consistent way, and allow configuring editors and tools for working with ALAN projects anywhere. When we adopt the same conventions, it's easier to work together in a smooth manner.
The configuration files for Git and EditorConfig cover the following Alan-specific files extensions:
| ext | description |
|---|---|
.alan |
Alan source files. |
.i |
Alan source modules. |
.a3s |
Alan commands script (aka solution files). |
.a3t |
Alan game transcripts. |
The .a3s and .a3t extension are the new official extensions adopted for command scripts and transcripts, respectively.
By default, the following Alan generated files will be excluded from the project:
| ext | description |
|---|---|
.a3c |
Alan compiled adventures. |
.ifid |
Source adventure IFID file. |
.log |
Compiler/ARun log files. |
.sav |
Saved games (used for testing). |
To structure and organize project directories and files, we use two-letter locale codes to represent the various spoken languages, according to the ISO 639-1:2002 standard.
Here are a few locale codes which are used in this project:
| language | code |
|---|---|
| English | en |
| French | fr |
| German | de |
| Spanish | es |
| Swedish | sv |
For the full list of ISO 639-1 language codes, see:
This repository adopts EditorConfig to enforce consistent code styles in the repository contents and across different editors and IDEs:
If you're using an editor or IDE that natively supports EditorConfig, code styling should be handled auto-magically in the background. If not, check if there's an EditorConfig plug-in/package for your editor/IDE that you can install.
Each PR and commit is tested on GitHub for code styles consistency via Travis CI, using the EClint validator for EditorConfig.
Travis CI validation is performed by the validate.sh script found in the repository root; you can run the script locally to check the integrity status of your repository folder (the script will check all files, including unstaged and ignored ones).
You're strongly advised to install EClint (Node.js) and our pre-commit Git hook to validate your changes for code consistency at commit time:
git-hook-install.sh— installs the pre-commit hook.git-hook-remove.sh— removes the pre-commit hook.
Once installed the pre-commit hook, every time you carry out a commit operation the staged files will be first checked via EClint to ensure that they meet the code styles settings in .editorconfig, and if they don't the commit will fail with an error listing the files that didn't pass the validation test.
NOTE — You can always bypass the pre-commit hook via the
--no-verifyoption, e.g.:git commit --no-verify
The advantage of using this hook instead of the validate.sh script is that the hook will test only the staged files involved in the actual commit, whereas the script will test every file in the repository folder, including ignored and unstaged files, which is more time consuming and not focused on the specific commit changes.
The git-hook-install.sh script will create the following files inside the repository:
.git/hooks/pre-commit-validate.sh— the commit validation script..git/hooks/pre-commit— the pre-commit hook that launches the validation script.
You can uninstall the Git hook at any time, by executing:
The hook installer and uninstaller scripts are designed to coexist with other pre-commit hooks you might have added to the repository, without disrupting them.
If you're planning to add a port of the Foundation Library to a new locale, here are some guidelines.
Each port to a new locale should abide to the following folders naming and structuring convention:
/alan_<locale-code>//Foundation/Library.i— main library import module.*.i— other library modules.
README.md— English README.README_<locale-code>.md— README in target locale.
Where <locale-code> stand for the two-letter code indicating the target locale (e.g. en, de, es), as described in the Locale Codes section of this document.
The main library import module should be named Library.i, regardless of the library locale.
(This module was called std.i in previous incarnations of the library.)
The other library modules should be named accorded to their meaning in the target locale — e.g. help.i would be translated to ayuda.i in Spanish, hilfe.i in German, aiuto.i in Italian, etc.).
The main README.md document in the alan_<locale-code>/ folder should be in English, for the benefit of all users and maintainer, since English is the standard communication language used in the ALAN IF community.
A README document in the target locale of the library should also be provided, named as README_<locale-code>.md, for the benefit of the library end users (who might not necessarily know English).
Naming the document this way is preferable to translating the filename to the target locale (e.g. LEEME.md for Spanish, LISEZMOI.md for French, or LEGGIMI.md for Italian), since the latter solution makes it less obvious to non-speakers of the target locale that it's a README document.
Inside the Foundation/ folder, you're free to name documents as you please, since its contents are for the exclusive benefit of speakers of the target locale.