Guidelines for contributing to the Awesome Interactive Fiction project.
For detailed instructions on how to build the documents, see:
Table of Contents
- Pull Requests vs Issues
- Submitting Contents via Pull Requests
- Proposing Contents via Issues
- External Links
You can contribute to the Awesome Interactive Fiction project via:
The former contribution method is the preferred one, for you'll be directly contributing your contents to the AsciiDoc source files; but it's more indicated for those willing to collaborate to the project on the long run, for it requires some initial setup steps, and knowledge of AsciiDoc.
Issues are useful for discussion and planning, but can also be used to propose new material by those who don't know AsciiDoc, or simply wish to propose adding a link and don't want to go through all the trouble of forking the repository.
Here are some notes and guidelines for those willing to contribute to the project via Git.
The source files of the Awesome IF document are stored inside the docs_src/ subfolder, along with detailed info on the various files and build instructions:
For editing convenience, the (rather long) Awesome IF document was split into multiple files — one file per document section. (More info in docs_src/README.md).
The README.adoc file that you see in the repository main page is generated by preprocessing all the source files into a single AsciiDoc document, so that visitors landing on the repository will be presented with a preview of the full Awesome IF document.
This duplicate document is necessary because GitHub does not currently support AsciiDoc include:: directives.
IMPORTANT — You should not edit the
README.adocfile, for all changes would be overwritten when the project is updated. Edit its source files indocs_src/instead.
Before creating a pull request, you should first validate locally that all changed files are compliant to the EditorConfig settings of this project.
The tool of choice for validating this repository is the EClint validation tool (Node.js) — the tool used on Travis CI to validate all commits and pull requests.
To execute the validation tests locally, you can either:
-
Run in your shell the
./validate.shscript, or -
Open a shell/CMD in the project root and type:
$ eclint check
Source documents are in AsciiDoc format, designed for Asciidoctor (Ruby), so you'll need to install the Asciidoctor Ruby gem on your machine to be able to build and preview the edited document.
This repository relies on EditorConfig to enforce consistent code styles in the project and across different editors.
Many modern editors will automatically pick-up the correct settings from the .editorconfig file, so you won't have to worry about details like indentation size and style, etc.
If your editor doesn't natively support EditorConfig, you should find and install a third party plug-in.
EditorConfig validation of the project files is carried out via Travis CI on every commit and pull request using the EClint validation tool (Node.js).
You should install EClint on your machine via NPM, in order to check locally that all files pass the validation test, before submitting a pull request:
npm install -g eclint
In any case, neither the use of an EditorConfig plug-in nor the ECLint tool are mandatory; they are just highly recommended ways to optimize your workflow locally and to help preserving code consistency in the repository.
The repository issues can be freely used to propose new links, discuss the project, offer advise, ask questions, or anything else that is related to the project goals — there are no strict rules regarding issues, for it's unlikely that this project will ever end up being sumberged in thousands of pending issues.
In the long term, it's likely that most contributions will come via issues, from visitors who noticed that some resources are not listed, and open an issue to mention their omission and provide links to them.
- AsciiDoc — WikiPedia page.
- Asciidoctor
- EditorConfig
Some useful articles and tutorials for Git newbies:
- Github's Fork & Pull Workflow for Git Beginners — introductory article by Tom Hombergs.