Contributing to DITA Open Toolkit
You can help us make the toolkit better by finding and reporting bugs, participating in community support, and improving the code and documentation.
Reporting bugs
We use GitHub as our issue tracker. There you can submit bug reports and make feature suggestions. If you find a bug and you don’t know how to fix it, create an issue to request changes.
Before you do that, review the open issues to make sure it hasn’t already been reported. We have separate issue trackers for the documentation and website code.
Community support
You can help give back to the community by answering DITA-OT–related questions on the DITA-OT Discussions forum on GitHub, the DITA Users group, or Stack Overflow.
Development discussions
We use Slack to discuss DITA-OT development and design issues, plan events and keep tabs on revisions in our GitHub repositories. Developers and vendors using the toolkit are encouraged to join the DITA-OT Slack workspace to discuss upcoming changes.
To request an invitation and join the conversation, visit slack.dita-ot.org.
Coding
Have XSLT or Java coding skills?
You can contribute fixes to bugs or new features by sending pull requests via GitHub, the process of which is described in this Contributing to the Toolkit video.
Documentation
Have writing or editing skills?
If you find something wrong or missing in the documentation, you can open an issue on GitHub to describe the problem or suggest new topics we might want to include in future versions of the DITA-OT docs.
If you’d like to fix a typo or propose changes to an existing topic, you can use the Edit this page link in the page footers of the development version of the documentation to open the source file in a web editor and save your changes to a GitHub pull request. This video explains the contribution process for the DITA-OT documentation.
Signing your work
Before we can include your contribution in the DITA Open Toolkit, you need to give us your permission.
As the author of any creative work (including source code, or documentation), you control the copyright for that work. The DITA-OT project can’t legally use your contribution unless you allow us to.
To manage this process, the DITA-OT project uses a mechanism called a Developer Certificate of Origin (DCO) popularized by The Linux Foundation. The DCO is a legally binding statement that asserts that you are the creator of your contribution, and that you license the work under the Apache License Version 2.0.
To indicate that you agree to the terms of the DCO, you “sign off” your contribution by adding a line with your name and e-mail address to every Git commit message:
Signed-off-by: Jane Doe <jane.doe@example.com>
You must use your real name (no pseudonyms or anonymous contributions are allowed.)
Your signature certifies that you are either the author of the contribution or have the right to submit it under the open-source license used by the DITA Open Toolkit project.
If you set your user.name and user.email as part of your Git configuration, you can sign your commit automatically with git commit -s.
Adding signoff to earlier commits
To sign off your last commit from the command line, use:
git commit --amend --signoff
Then force-push to update the branch on your fork with:
git push --force-with-lease
Signing off with a Git client
Popular Git clients like Sourcetree allow you to sign off commits via a graphical user interface.
While each client handles this differently, the basic process remains the same. Look for commit options in the repository settings or near the field where you enter your commit message:
- Select the option to amend (change) your last commit.
- Select the option to sign off.
- You can then push the branch, making sure to select the “force push” option to update the branch in your pull request with the new (signed off) version of your commit.