How to contribute
Every block is a public repository under github.com/quran-ws, and issues and pull requests are open on all of them. This page says where each kind of change goes and what a pull request needs so it can be merged. If you want to use a block rather than change one, start at Choosing a block.
Three kinds of change, three places
| You want to | Go to | How |
|---|---|---|
| Correct or add a rule, a term in the dictionary, or a guideline page | quran-ws/docs | Open an issue first, with one of its three forms: propose a term, propose a guideline, suggest an edit. A one-paragraph fix or a typo goes straight to a pull request. |
| Correct data or code in a block: a wrong ayah boundary, a mis-traced ornament, a bug in a client library | that block's repository, linked from its reference page and from its README | Open an issue or a pull request there. The README's last section maps the repository and names the checks that must stay green. |
| Report something wrong on this site: a dead link, a number that no longer matches the data, a page that misleads | quran-ws/docs issues with the page's URL | The site reads its guidelines and its demo data from the repositories, so a fact that is wrong here is usually wrong at its source; say where you saw it and it will be fixed in both. |
Most "new" terms are a spelling of an entry that already exists. Search the dictionary first, or run the lookup script in the guidelines repository:
python3 skills/quranic-terminology/scripts/lookup.py --search waqf
What every pull request needs
- The case behind it. A change to a rule or a term names the project and the place where the current wording was ambiguous or impossible, or the issue where that was discussed. A rule with no case behind it is not adopted, so this is the part that gets a proposal merged.
- Green checks. Each repository carries its own gates,
tests/orconformance/, and its README says how to run them. In the guidelines repository the command ispython3 tools/build.pyfollowed bypython3 -m pytest -q, and the generated files it rewrites go in the same pull request. - The Qurʾānic text left alone. No pull request types, corrects or normalises the text by hand. A defect in the text is a defect in the source package it was read from, and it is fixed there, with a second reviewer, under Qurʾān text and Versioning and corrections.
- Both languages, when the page has both. A guideline page is written once, in one rule file, with its Arabic beside its English, so a change to the wording changes both or says which one is waiting.
Pages that are still a proposal
Nothing in the guidelines is adopted yet. Each page carries a status: draft, proposed or
adopted. A proposal is exactly what a contributor can change most easily, and the discussion
that changes it happens in the issue, not in the pull request. What concerns the Qurʾānic text
itself is reviewed by qualified scholars before it is adopted; what concerns engineering is one
defensible choice among several, and a better one, with its case, is welcome.
Licence of what you send
Each repository names its licence at the top of its LICENSE file, MIT for code and CC BY 4.0 for
data and prose, directory by directory. A contribution is published under the licence of the
directory it lands in. Licensing has the table.