CONTRIBUTING.md

Contributing to the DITA-OT docs

We welcome your contributions to the DITA-OT documentation.

Thanks for your interest — here's how you can help us “write the docs.”

Creating an issue

If you find a bug or would like to suggest a new topic for the DITA-OT docs, create an issue:

1. Search dita-ot/docs/issues to ensure your issue hasn't already been reported.
2. Create an issue. If it's a bug, provide steps to recreate the issue.
3. Send a pull request. If you know how to fix the issue yourself, submit a pull request with the proposed changes.

Read on for details…

Submitting pull requests

Good pull requests—corrections, improvements, new topics—are a great help. They should remain focused in scope and shouldn't contain unrelated commits.

Follow this process to ensure your contribution meets our expectations and increase the chances that your changes will be included:

1. Fork the docs repository, clone your fork, and configure the remotes:

   # Clone your docs fork into the current directory
   git clone https://github.com/<your-username>/docs
   
   # Navigate to the newly cloned directory
   cd docs
   
   # Assign the original repo to a remote called "upstream"
   git remote add upstream https://github.com/dita-ot/docs

2. If you cloned a while ago, get the latest changes from upstream:

   git checkout develop
   git pull upstream develop

3. Create a new feature branch (off the upstream project's develop branch) for your new feature, change, or fix:

   git checkout -b your-new-branch

4. Commit your changes in logical chunks.

   Please be sure to follow the coding guidelines and best practices outlined in the docs project wiki:

   • Test before committing
   • Commit related changes
   • Commit often
   • Write good commit messages

   Use Git's interactive rebase feature to tidy up your commits, if necessary, before making them public.

5. Indicate that you agree to the terms of the Apache License Version 2.0 by "signing off" your contribution with git commit -s.

   This adds a line with your name and e-mail address to your Git commit message:

    Signed-off-by: Jane Doe <[email protected]>

6. Locally merge (or rebase) the upstream develop branch into your feature branch:

   git pull [--rebase] upstream develop

7. Push your feature branch up to your fork:

   git push origin your-new-branch

8. Open a pull request with a clear title and description.

   Pro tip: If there's no corresponding issue for the changes you're proposing, there's no need to create one first. You can describe the problem and provide the solution all in one step. (Under the hood, pull requests are just a special type of issue.)