Working on Documentation

How Cassandra is documented

Antora, to create pages hosted at cassandra.apache.org. wiki (not covered by this guide). -→ AsciiDoc, the markup language used to generate our documentation. Markup languages allow you to format text using certain syntax elements. Your document structure will also have to follow specific conventions. Feel free to take a look at existing documents to get a better idea how we structure our documents. So how do you actually start making contributions?

GitHub based work flow

Recommended for shorter documents and minor changes on existing content (e.g. fixing typos or updating descriptions) Follow these steps to contribute using GitHub. It’s assumed that you’re logged in with an existing account.

1. Cassandra repository 1.
2. doc/source/modules to find the .adoc file to edit. The URL of the document should correspond to the directory structure within the modules, where first the component name, such as cassandra is listed, and then the actual pages inside the pages directory. New files can be created using the “Create new file” button:
3. .adoc files to get a better idea what format elements to use. Make sure to preview added content before committing any changes. 1. 1. Afterwards the GitHub Cassandra mirror will list your pull request and you’re done. Congratulations! Please give us some time to look at your suggested changes before we get back to you.

   Jira based work flow

   Recommended for major changes contribution guides as for regular code contributions. Creating high quality content takes a lot of effort. It’s therefore always a good idea to create a ticket before you start and explain what you’re planning to do. This will create the opportunity for other contributors and committers to comment on your ideas and work so far. Eventually your patch gets a formal review before it is committed.

   Working on documents locally using Antora

   Recommended for advanced editing doc/README.md. Setup is very easy (at least on OSX and Linux).

   Notes for committers

   Please feel free to get involved and merge pull requests created on the GitHub mirror if you’re a committer. As this is a read-only repository, you won’t be able to merge a PR directly on GitHub. You’ll have to commit the changes against the Apache repository with a comment that will close the PR when the committ syncs with GitHub. You may use a git work flow like this:

   git remote add github https://github.com/apache/cassandra.gitgit fetch github pull/<PR-ID>/head:<PR-ID>git checkout <PR-ID>

   Now either rebase or squash the commit, e.g. for squashing:

   git reset --soft origin/trunkgit commit --author <PR Author>

   Make sure to add a proper commit message including a “Closes #” text to automatically close the PR.

   Publishing

   here.