Difference between revisions of "Module Development Collaboration"

Revision as of 12:25, 31 August 2015

Version control

. CrossWire will provide to module teams who want to collaborate on a module following tools:

1. A private Git repository (access will be via SSH keys) which can act as a scrapbook and collaboration tool
2. Email notification system - all changes to the repository are automatically notified to all collaborators
3. Some templates for the repository and a bunch of scripts to make module making easy.

If you want to get such a repository on the CrossWire server please email to modules AT crosswire DOT org.

CrossWire itself uses a similar setup for its internal development and for the automatic (re)deployment of modules.

Directory structure

Our Github repository provides makefiles and scripts to setup a module making environment:

At the root is a bunch of makefile templates. Choose the appropriate, amend it as necessary and rename it "Makefile" and run

 make setup

The makefile will create and setup everything to get started. E.g. the makefile for USFM projects will create a structure like this

• mods.d -- SWORD module conf file
• modules -- compiled module data
• remotescripts -- scripts pulled in from elsewhere
• bin -- locally provided scripts
• osis -- OSIS docs for osis2mod or sharing with publisher/3rd parties
• usfm -- USFM for sharing with author or as an intermediate step in conversion

Depending on the project following directories might be useful.

• gobible -- compiled Go Bible applications (including any smaller collections)
• epub -- EPUB for publishing to ebooks
• thml -- ThML for import to Go Bible?
• usx -- USX for sharing with author or as an intermediate step in conversion
• docs -- documentation, correspondence with pubs/authors, permission letters, etc.
• orig -- source docs from publisher/author
• fixed -- source docs after correction of errors, inconsistencies, etc. in text or markup

bin

The bin directory (e.g. GerElberfelder above) would contain all module-specific scripts necessary for converting source files to modules and other output formats. So general purpose scripts like usfm2osis.py would not appear here, instead being installed at some system-wide location outside the tree or being pulled into the "remotescripts" directory.

ChangeLog

Following the approximate lead of Sword SVN, keep a ChangeLog for each module in the format:

[date in ISO 8601 format: yyyy-mm-dd]\t[contributor name <contributor email>]\n \t[comments]

Makefile

The makefile templates we offer run usually following

make clean     (delete all intermediate format files)
make deepclean (resets everything back to the first step, deleting work directories, intermediate files etc.)
make setup     (sets up a working environment with relevant directories, pulls in files, scripts etc)
make all       (create a finalised module ready for publication)
make tests     (run various tests on the files you have produced to find inconsistencies)
make publish     (push the finalised module out to a staging area and deploy in a repository)
make localdeploy (copy the finalised module into your own Sword installation to allow easy testing with your own CrossWire biblestudy programmes)

metadata

Metadata should be collated into a single file (maybe something XML to facilitate validation for automated generation & parsing) the incorporates all necessary metadata for all of our output formats (OSIS, ThML, TEI, EPUB/MOBI, Sword). Investigate Dublin Core & other metadata standards. Consider developing a set of private-use extensions to an existing standard and consistent methods of encoding all of our relevant .conf values in OSIS/ThML/TEI files.