Difference between revisions of "Module Submission"

From CrossWire Bible Society
Jump to: navigation, search
(Changes to reflect the upgraded publishing framework)
m (What's next?: Fix broken link)
 
(26 intermediate revisions by 2 users not shown)
Line 14: Line 14:
 
<references />
 
<references />
  
= How-To name your files =
+
= How-To name your source files =
The source files reflect the name of your module in '''lowercase''' followed by an extension.
 
  
For the configuration file, the extension is <code>.conf</code>.
+
You should provide 2 files:
 +
 
 +
* 1 Source text which will be converted to SWORD format. The source text must be unique and cannot be splitted in several files.
 +
* 1 Configuration file which tells Sword how to recognize and what to do with your module.
 +
 
 +
The files reflects the name of your module in '''lowercase''' followed by an extension.
  
Extensions for the text file:
+
Extensions for the text file are:
  
 
* OSIS: <code>.osis.xml</code>
 
* OSIS: <code>.osis.xml</code>
 
 
* TEI: <code>.tei.xml</code>
 
* TEI: <code>.tei.xml</code>
 
 
* VPL: <code>.vpl</code>
 
* VPL: <code>.vpl</code>
 
 
* IMP: <code>.imp</code>
 
* IMP: <code>.imp</code>
 +
* ThML: <code>.thml</code>
  
* ThML: <code>.thml</code>
+
For the configuration file, the extension is <code>.conf</code>.
  
 
So, for the <code>FreBDM1707</code> module encoded in OSIS, we have <code>frebdm1707.osis.xml</code> and <code>frebdm1707.conf</code> files.
 
So, for the <code>FreBDM1707</code> module encoded in OSIS, we have <code>frebdm1707.osis.xml</code> and <code>frebdm1707.conf</code> files.
  
= How-To prepare your files =
+
= How-To prepare your source files =
  
 
We will accept only plain texts in VPL<ref name="vpl">Only for Bibles in KJV versification</ref>  or texts marked up in OSIS or TEI, with the sole exception texts based on CCEL documents that are marked up in ThML.
 
We will accept only plain texts in VPL<ref name="vpl">Only for Bibles in KJV versification</ref>  or texts marked up in OSIS or TEI, with the sole exception texts based on CCEL documents that are marked up in ThML.
Line 65: Line 67:
 
We require that the following minimum set of module configuration fields are included: <code>Description</code>, <code>About</code>, <code>DistributionLicense</code>, and <code>TextSource</code>. Ensure that your module complies with our stated copyright policy.
 
We require that the following minimum set of module configuration fields are included: <code>Description</code>, <code>About</code>, <code>DistributionLicense</code>, and <code>TextSource</code>. Ensure that your module complies with our stated copyright policy.
  
== Copyrighted Material ==
+
= Copyrighted Material =
 
If your got permission to distribute a new module which is under copyright, please send a copy of the authorization in a file named copyright.<extension> like <code>copyright.pdf</code>, <code>copyright.png</code>...
 
If your got permission to distribute a new module which is under copyright, please send a copy of the authorization in a file named copyright.<extension> like <code>copyright.pdf</code>, <code>copyright.png</code>...
  
= Submit your files =
+
= Other files =
Submit only source files. Do not submit built modules that you have imported to Sword format.
 
  
Send an email to [mailto:modules@crosswire.org modules@crosswire.org] describing the module and your files with one of the options below:
+
Besides source, conf and copyright files we accept:
 +
* Cascading style sheet (CSS) file used to format the contents of a module
 +
* Media subdir containing multimedia files, commonly <code>Images</code> subdir.
 +
 
 +
= How-To submit your files =
 +
Submit only source files. Do not submit built modules that you have imported to Sword format. Avoid spaces in folder and file names.
 +
 
 +
Send an email to <code>modules@crosswire.org</code> describing the module and your files with one of the options below:
 +
 
 +
''Note: Pressing one of the following modules@crosswire.org links will open a new mail window already filled with a sample text.''
  
 
== Files attached ==
 
== Files attached ==
  
 
It is highly recommended to zip your files, as they are text files they will be highly compressed with the double benefit to reduce storage and make transmitting them much easier.
 
It is highly recommended to zip your files, as they are text files they will be highly compressed with the double benefit to reduce storage and make transmitting them much easier.
Feel free to attach your zip file to the email sent to [mailto:modules@crosswire.org modules@crosswire.org]. Actually the biggest file (30MB) we have is 3MB once zipped.
+
Feel free to attach your zip file to the email sent to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Please%20find%20the%20attached%20zip%20archive%20with%20source%20and%20.conf%20files.%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org]. Actually the biggest file (30MB) we have is 3MB once zipped. Supported file formats: <code>tar.gz</code>; <code>tgz</code>; <code>tar.bz2</code>; <code>tb2</code>; <code>bz2</code>; <code>gz</code>; <code>zip</code>; <code>gmx</code>; <code>Z</code>; <code>7z</code>
  
 
== Link to a zip file ==
 
== Link to a zip file ==
  
If you own a repository on the Internet, you may also store your zipped file on your repository and send the URL to this file instead.
+
If you own a repository on the Internet, you may also store your zipped file on your repository and send the URL to this file instead to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20zip%20archive%20of%20the%20module%20with%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].
  
== Link to git Repository ==
+
== Link to a git Repository ==
  
If you built your module on a public Git/GitLab/GitHub, you may want to share the <code>git clone</code> URL in the email.
+
If you built your module on a public Git/GitLab/GitHub, you may want to share the <code>git clone</code> URL in the email to [mailto:modules@crosswire.org?subject=Module%20submission%3A%20%3Cyour-module%3E&body=Here%20is%20the%20link%20to%20the%20Git%20repository%20of%20the%20module%20containing%20source%20and%20.conf%20files%3A%20%3Curl%3E%0D%0A%0D%0AModule%20Name%20(CamelCase)%3A%0D%0AVersion%3A%20%0D%0AChangelog%3A%20%3CWhat's%20new%3E%0D%0AType%3A%20%3CBible%2FCommentary%2FGenBook%2FLexDict%3E%0D%0ASource%20Type%3A%20%3COSIS%2FTEI%2F..%2F..%3E%20%0D%0AVersification%20(optional)%3A%20%0D%0A%0D%0AThanks!%0D%0A modules@crosswire.org].
  
 
We do accept git URL but there are some limitations, though:
 
We do accept git URL but there are some limitations, though:
  
* We expect to run into a flat structure, so Module files (source, .conf) shouldn't go in a subdir. Optional files like copyright, style.css should be at the root of your repository as well. Only multimedia files (audio/video/images) should go in their own subdir, typically <code>images</code> for dictionaries.
+
* We expect to run into a flat structure, so:
* For upgraded modules, we'll clone tagged releases, so you have to mark your release by running <code>git tag <version></code>.
+
** Module files (source, .conf) shouldn't go into a subdir
* If you keep the original source text in plain format, USFM ot whatever in a subdir, please add this subdir to .gitignore as we are not very interested in cloning it.
+
** Optional files like copyright, style.css must be at the root of your repository
 +
** Only multimedia files (audio/video/images) should go in their own subdir, typically <code>images</code> for dictionaries
 +
** A script subdir containing tools for converting an original source file to OSIS is welcome
 +
 
 +
Example:
 +
<pre>
 +
  git
 +
  | 
 +
  +-- copyright.pdf
 +
  +-- images/
 +
  +-- module.osis.xml
 +
  +-- module.conf
 +
  +-- script/
 +
  +-- style.css
 +
  +-- README.md
 +
</pre>
 +
* Try to not put other files in the repository, they are more misleading than handy. Original text URL should be linked in <code>README.md</code>. If you really need to keep the original source text in plain format, USFM ot whatever in a subdir, please add this subdir to .gitignore.
 +
<code>$ echo sources/ >> .gitignore</code>
 +
 
 +
* No more than 1 module per git repository.
 +
 
  
 
It is sometimes easier to run <code>git archive</code> and attach the resulting zip file to the email.
 
It is sometimes easier to run <code>git archive</code> and attach the resulting zip file to the email.
 +
 +
 +
 +
= What's next? =
 +
Modules submitted to Crosswire are generally reviewed as quickly as possible, most are often accepted.
 +
 +
We build a binary version by using our creation and diagnostic tools: https://wiki.crosswire.org/File_Formats#The_SWORD_Project_Utilities.
 +
 +
== Build failure ==
 +
If the build fails, you'll be noticed by this mail:
 +
 +
<pre>
 +
This is to announce that fatal errors were encountered
 +
while processing the module <your-module> which caused
 +
the build to fail.
 +
 +
Please refer to the attached build log for more details
 +
about the error encountered.
 +
 +
Useful information to fix the problem can be found in
 +
our Wiki in the '''Module development''' section at:
 +
https://wiki.crosswire.org.
 +
 +
yours,
 +
 +
P.S.: This email is sent automatically.
 +
 +
</pre>
 +
 +
It’s OK to make mistakes, so do not be discouraged, read the build log and if you find anything that is unclear along the way, do not hesitate to ask questions. Then, once fixed, don't hesitate to re-send your corrected module.
 +
 +
== Successful build ==
 +
The build was sucessful, you'll receive this mail:
 +
 +
<pre>
 +
This is to announce that we have just now uploaded <your-module>
 +
in the CrossWire beta repository for testing purposes.
 +
 +
If no raised concern nor a quality alert has been sent on the list,
 +
<your-module> will be published in a week.
 +
 +
Many thanks to everyone who contributed to this release.
 +
 +
yours
 +
 +
P.S.: This email is sent automatically.
 +
 +
</pre>
 +
 +
Your module is now available to download from the Beta repository. It will be tested in this repository for around a week, and if everything is ok it will be regularly published.
  
  
Line 98: Line 178:
 
<div style="text-align:center">'''If you do not comply with the above your module submission might end up being deprioritised and will certainly not get uploaded as fast as it could be otherwise'''</div>
 
<div style="text-align:center">'''If you do not comply with the above your module submission might end up being deprioritised and will certainly not get uploaded as fast as it could be otherwise'''</div>
 
----
 
----
 +
  
  
 
Please note: Do not edit this page unless you are actually ''directly'' involved with uploading modules onto the server. If you have a comment or addition to make, but you are not part of this particular effort, please use talk page.
 
Please note: Do not edit this page unless you are actually ''directly'' involved with uploading modules onto the server. If you have a comment or addition to make, but you are not part of this particular effort, please use talk page.
 
[[Category:Modules]]
 
[[Category:Modules]]

Latest revision as of 14:32, 15 June 2023


For information on module licensing → please look at DevTools:Module Submission and Copyrights



How-To Name your module

Each module needs a name that be used as a unique identifier. Valid characters for the name are limited to alphanumeric characters, numeric characters and underscore. PCRE class [A-Za-z0-9\_].

Normalized names of module contains usually[1] 3 letters for language, followed by a short name descibing the work. Language is encoded in ISO 639-3 code. See [1] for a list of codes.

The name has to be set in CamelCase format. Example for The French Bible David Martin 1707: FreBDM1707[2]

  1. For historical reasons, modules in English do not have any language prefix.
  2. The published year was added to differentiate this version from successive revisions in 1744, 1855. Otherwise we could just have named it FreBDM.

How-To name your source files

You should provide 2 files:

  • 1 Source text which will be converted to SWORD format. The source text must be unique and cannot be splitted in several files.
  • 1 Configuration file which tells Sword how to recognize and what to do with your module.

The files reflects the name of your module in lowercase followed by an extension.

Extensions for the text file are:

  • OSIS: .osis.xml
  • TEI: .tei.xml
  • VPL: .vpl
  • IMP: .imp
  • ThML: .thml

For the configuration file, the extension is .conf.

So, for the FreBDM1707 module encoded in OSIS, we have frebdm1707.osis.xml and frebdm1707.conf files.

How-To prepare your source files

We will accept only plain texts in VPL[1] or texts marked up in OSIS or TEI, with the sole exception texts based on CCEL documents that are marked up in ThML.

  1. Only for Bibles in KJV versification

Check your OSIS before submitting

OSIS 2.1 is now the preferred format for Bibles, Commentaries and General Books. TEI is the prefered format for dictionaries.

OSIS texts need to have the CamelCase module name as workID and an appropriate osisRefWork entry within the appropriate header section. The document language needs to be set correctly, ISO 639-1 codes are preferred, and ISO 639-3 codes when ISO 639-1 codes do not exist for the given language. Examples:

Bible:

<osisText osisIDWork="MyModule" osisRefWork="Bible" xml:lang="he">

Commentary:

<osisText osisIDWork="MyModule" osisRefWork="Commentary" xml:lang="gr">

General Book:

<osisText osisIDWork="MyModule" osisRefWork="GenBook" xml:lang="en">

Please validate your OSIS or TEI text

See: Guide to Validate_OSIS_or_TEI_text

Check your configuration file

We require that the following minimum set of module configuration fields are included: Description, About, DistributionLicense, and TextSource. Ensure that your module complies with our stated copyright policy.

Copyrighted Material

If your got permission to distribute a new module which is under copyright, please send a copy of the authorization in a file named copyright.<extension> like copyright.pdf, copyright.png...

Other files

Besides source, conf and copyright files we accept:

  • Cascading style sheet (CSS) file used to format the contents of a module
  • Media subdir containing multimedia files, commonly Images subdir.

How-To submit your files

Submit only source files. Do not submit built modules that you have imported to Sword format. Avoid spaces in folder and file names.

Send an email to modules@crosswire.org describing the module and your files with one of the options below:

Note: Pressing one of the following modules@crosswire.org links will open a new mail window already filled with a sample text.

Files attached

It is highly recommended to zip your files, as they are text files they will be highly compressed with the double benefit to reduce storage and make transmitting them much easier. Feel free to attach your zip file to the email sent to modules@crosswire.org. Actually the biggest file (30MB) we have is 3MB once zipped. Supported file formats: tar.gz; tgz; tar.bz2; tb2; bz2; gz; zip; gmx; Z; 7z

Link to a zip file

If you own a repository on the Internet, you may also store your zipped file on your repository and send the URL to this file instead to modules@crosswire.org.

Link to a git Repository

If you built your module on a public Git/GitLab/GitHub, you may want to share the git clone URL in the email to modules@crosswire.org.

We do accept git URL but there are some limitations, though:

  • We expect to run into a flat structure, so:
    • Module files (source, .conf) shouldn't go into a subdir
    • Optional files like copyright, style.css must be at the root of your repository
    • Only multimedia files (audio/video/images) should go in their own subdir, typically images for dictionaries
    • A script subdir containing tools for converting an original source file to OSIS is welcome

Example:

  git
   |  
   +-- copyright.pdf
   +-- images/
   +-- module.osis.xml
   +-- module.conf
   +-- script/
   +-- style.css
   +-- README.md
  • Try to not put other files in the repository, they are more misleading than handy. Original text URL should be linked in README.md. If you really need to keep the original source text in plain format, USFM ot whatever in a subdir, please add this subdir to .gitignore.

$ echo sources/ >> .gitignore

  • No more than 1 module per git repository.


It is sometimes easier to run git archive and attach the resulting zip file to the email.


What's next?

Modules submitted to Crosswire are generally reviewed as quickly as possible, most are often accepted.

We build a binary version by using our creation and diagnostic tools: https://wiki.crosswire.org/File_Formats#The_SWORD_Project_Utilities.

Build failure

If the build fails, you'll be noticed by this mail:

This is to announce that fatal errors were encountered
while processing the module <your-module> which caused
the build to fail.

Please refer to the attached build log for more details
about the error encountered.

Useful information to fix the problem can be found in
our Wiki in the '''Module development''' section at:
https://wiki.crosswire.org.

yours,

P.S.: This email is sent automatically.

It’s OK to make mistakes, so do not be discouraged, read the build log and if you find anything that is unclear along the way, do not hesitate to ask questions. Then, once fixed, don't hesitate to re-send your corrected module.

Successful build

The build was sucessful, you'll receive this mail:

This is to announce that we have just now uploaded <your-module>
in the CrossWire beta repository for testing purposes.

If no raised concern nor a quality alert has been sent on the list,
<your-module> will be published in a week.

Many thanks to everyone who contributed to this release.

yours

P.S.: This email is sent automatically.

Your module is now available to download from the Beta repository. It will be tested in this repository for around a week, and if everything is ok it will be regularly published.



If you do not comply with the above your module submission might end up being deprioritised and will certainly not get uploaded as fast as it could be otherwise


Please note: Do not edit this page unless you are actually directly involved with uploading modules onto the server. If you have a comment or addition to make, but you are not part of this particular effort, please use talk page.