| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="utf-8"> |
| <meta name="viewport" content="width=device-width,initial-scale=1.0"> |
| <title>Apache Cassandra | Apache Cassandra Documentation</title> |
| <link rel="stylesheet" href="../../assets/css/site.css"> |
| <link rel="schema.dcterms" href="https://purl.org/dc/terms/"> |
| <meta name="dcterms.subject" content="_"> |
| <meta name="dcterms.identifier" content="master"> |
| <meta name="generator" content="Antora 2.3.4"> |
| <link rel="icon" href="../../assets/img/favicon.ico" type="image/x-icon"> |
| <script> |
| const script = document.createElement("script"); |
| const domain = window.location.hostname; |
| script.type = "text/javascript"; |
| script.src = "https://plausible.cassandra.apache.org/js/plausible.js"; |
| script.setAttribute("data-domain",domain); |
| script.setAttribute("defer",'true'); |
| script.setAttribute("async",'true'); |
| document.getElementsByTagName("head")[0].appendChild(script); |
| </script> </head> |
| <body class="basic "> |
| <div class="container mx-auto relative"> |
| <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"></script> |
| <meta property="og:type" content="website" /> |
| <meta property="og:url" content="/" /> |
| <meta property="og:site_name" content="Apache Cassandra" /> |
| |
| <header id="top-nav"> |
| <div class="inner relative"> |
| <div class="header-social-icons text-right"> |
| <a href="https://twitter.com/cassandra?lang=en" target="_blank" styles="margin-left: 20px;"><img src="../../assets/img/twitter-icon-circle-white.svg" alt="twitter icon" width="24"></a> |
| <a href="https://www.linkedin.com/company/apache-cassandra/" target="_blank" styles="margin-left: 20px;"><img src="../../assets/img/LI-In-Bug.png" alt="linked-in icon" width="24"></a> |
| <a href="https://www.youtube.com/c/PlanetCassandra" target="_blank" styles="margin-left: 20px;"><img src="../../assets/img/youtube-icon.png" alt="youtube icon" width="24"></a> |
| </div> |
| <div class="cf"> |
| <div class="logo left"><a href="/"><img src="../../assets/img/logo-white-r.png" alt="cassandra logo"></a></div> |
| <div class="mobile-nav-icon right"> |
| <img class="toggle-icon" src="../../assets/img/hamburger-nav.svg"> |
| </div> |
| <ul class="main-nav nav-links right flex flex-vert-center flex-space-between"> |
| <li> |
| <a class="nav-link hide-mobile">Get Started</a> |
| <ul class="sub-menu bg-white"> |
| <li class="pa-micro"> |
| <a href="/_/cassandra-basics.html"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-basics.png" alt="cassandra basics icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Cassandra Basics |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro"> |
| <a href="/_/quickstart.html"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-rocket.png" alt="cassandra basics icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Quickstart |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro"> |
| <a href="/_/ecosystem.html"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-ecosystem.png" alt="cassandra basics icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Ecosystem |
| </div> |
| </a> |
| </li> |
| </ul> |
| </li> |
| <li><a class="nav-link" href="/doc/latest/">Documentation</a></li> |
| <li> |
| <a class="nav-link" href="/_/community.html">Community</a> |
| <ul class="sub-menu bg-white"> |
| <li class="pa-micro"> |
| <a href="/_/community.html#code-of-conduct"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-welcome.png" alt="welcome icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Welcome |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro hide-mobile"> |
| <a href="/_/community.html#discussions"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-discussions.png" alt="discussions icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Discussions |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro hide-mobile"> |
| <a href="/_/community.html#project-governance"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-governance.png" alt="Governance icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Governance |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro hide-mobile"> |
| <a href="/_/community.html#how-to-contribute"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-contribute.png" alt="Contribute icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Contribute |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro hide-mobile"> |
| <a href="/_/community.html#meet-the-community"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-community.png" alt="Meet the Community icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Meet the Community |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro hide-mobile"> |
| <a href="/_/cassandra-catalyst-program.html"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-catalyst.png" alt="Catalyst icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Catalyst Program |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro hide-mobile"> |
| <a href="/_/events.html"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-events.png" alt="Events icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Events |
| </div> |
| </a> |
| </li> |
| </ul> |
| </li> |
| <li> |
| <a class="nav-link hide-mobile">Learn</a> |
| <ul class="sub-menu bg-white"> |
| <li class="pa-micro"> |
| <a href="/_/Apache-Cassandra-5.0-Moving-Toward-an-AI-Driven-Future.html"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-basics.png" alt="Basics icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Cassandra 5.0 |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro"> |
| <a href="/_/case-studies.html"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-case-study.png" alt="Case Studies icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Case Studies |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro"> |
| <a href="/_/resources.html"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-resources.png" alt="Resources icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Resources |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro"> |
| <a href="/_/blog.html"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-blog.png" alt="Blog icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Blog |
| </div> |
| </a> |
| </li> |
| </ul> |
| </li> |
| <li><a class="nav-link btn btn--filled" href="/_/download.html">Download Now</a></li> |
| </ul> |
| </div> |
| </div> |
| </header> |
| |
| <div class="hero hero--home grad"> |
| <div class="eye"></div> |
| <div id="home-content" class="text-center flex flex-center flex-column relative z2 ma-xlarge"> |
| <h1>Working on Documentation</h1> |
| </div> |
| </div> |
| <div class="flex-center py-large arrow"> |
| <div class="inner inner--narrow"> |
| <div class="sect1"> |
| <h2 id="working-on-documentation"><a class="anchor" href="#working-on-documentation"></a>Working on Documentation</h2> |
| <div class="sectionbody"> |
| <div class="sect2"> |
| <h3 id="how-cassandra-is-documented"><a class="anchor" href="#how-cassandra-is-documented"></a>How Cassandra is documented</h3> |
| <div class="paragraph"> |
| <p>The official Cassandra documentation lives in the project’s git |
| repository. |
| We use a static site generator, <a href="http://www.antora.org/">Antora</a>, to create pages hosted at |
| <a href="/doc/latest/">cassandra.apache.org</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p><!-- You’ll also find developer-centric content about Cassandra internals in our |
| retired <a href="https://wiki.apache.org/cassandra">wiki</a> (not covered by this |
| guide). -→</p> |
| </div> |
| <div class="paragraph"> |
| <p>Using a static site generator often requires the use of a markup language |
| instead of visual editors (which some people would call good news). |
| Antora processes <a href="http://www.asciidoc.org">AsciiDoc</a>, 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 <a href="/doc/">existing documents</a> to get a better idea how we structure our documents.</p> |
| </div> |
| <div class="paragraph"> |
| <p>So how do you actually start making contributions?</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="github-based-work-flow"><a class="anchor" href="#github-based-work-flow"></a>GitHub based work flow</h3> |
| <div class="paragraph"> |
| <p><em>Recommended for shorter documents and minor changes on existing content |
| (e.g. fixing typos or updating descriptions)</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>Follow these steps to contribute using GitHub. It’s assumed that you’re |
| logged in with an existing account.</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Fork the GitHub mirror of the |
| <a href="https://github.com/apache/cassandra">Cassandra repository</a></p> |
| </li> |
| </ol> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="../_images/docs_fork.png" alt="image"> |
| </div> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic" start="2"> |
| <li> |
| <p>Create a new branch that you can use to make your edits. It’s |
| recommended to have a separate branch for each of your working projects. |
| It will also make it easier to create a pull request later to when you |
| decide you’re ready to contribute your work.</p> |
| </li> |
| </ol> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="../_images/docs_create_branch.png" alt="image"> |
| </div> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic" start="3"> |
| <li> |
| <p>Navigate to document sources <code>doc/source/modules</code> to find the <code>.adoc</code> file to |
| edit. The URL of the document should correspond to the directory |
| structure within the modules, where first the <code>component</code> name, such as <code>cassandra</code> is listed, and then the actual pages inside the <code>pages</code> directory. New files can be created using the "Create new file" button:</p> |
| </li> |
| </ol> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="../_images/docs_create_file.png" alt="image"> |
| </div> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic" start="4"> |
| <li> |
| <p>At this point you should be able to edit the file using the GitHub web |
| editor. Start by naming your file and add some content. Have a look at |
| other existing <code>.adoc</code> files to get a better idea what format elements to |
| use.</p> |
| </li> |
| </ol> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="../_images/docs_editor.png" alt="image"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Make sure to preview added content before committing any changes.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="../_images/docs_preview.png" alt="image"> |
| </div> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic" start="5"> |
| <li> |
| <p>Commit your work when you’re done. Make sure to add a short |
| description of all your edits since the last time you committed before.</p> |
| </li> |
| </ol> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="../_images/docs_commit.png" alt="image"> |
| </div> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic" start="6"> |
| <li> |
| <p>Finally if you decide that you’re done working on your branch, it’s |
| time to create a pull request!</p> |
| </li> |
| </ol> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="../_images/docs_pr.png" alt="image"> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="jira-based-work-flow"><a class="anchor" href="#jira-based-work-flow"></a>Jira based work flow</h3> |
| <div class="paragraph"> |
| <p><em>Recommended for major changes</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>Significant changes to the documentation are best managed through our |
| Jira issue tracker. Please follow the same |
| <a href="patches.html" class="page">contribution |
| guides</a> 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.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="working-on-documents-locally-using-antora"><a class="anchor" href="#working-on-documents-locally-using-antora"></a>Working on documents locally using Antora</h3> |
| <div class="paragraph"> |
| <p><em>Recommended for advanced editing</em></p> |
| </div> |
| <div class="paragraph"> |
| <p>Using the GitHub web interface should allow you to use most common |
| layout elements including images. More advanced formatting options and |
| navigation elements depend on Antora to render correctly. Therefore, it’s |
| a good idea to setup Antora locally for any serious editing. Please |
| follow the instructions in the Cassandra source directory at |
| <code>doc/README.md</code>. Setup is very easy (at least on OSX and Linux).</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="notes-for-committers"><a class="anchor" href="#notes-for-committers"></a>Notes for committers</h3> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| <div class="paragraph"> |
| <p>You may use a git work flow like this:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>git remote add github https://github.com/apache/cassandra.git |
| git fetch github pull/<PR-ID>/head:<PR-ID> |
| git checkout <PR-ID></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Now either rebase or squash the commit, e.g. for squashing:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>git reset --soft origin/trunk |
| git commit --author <PR Author></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Make sure to add a proper commit message including a "Closes #<PR-ID>" |
| text to automatically close the PR.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="publishing"><a class="anchor" href="#publishing"></a>Publishing</h4> |
| <div class="paragraph"> |
| <p>Details for building and publishing of the site at cassandra.apache.org |
| can be found |
| <a href="https://github.com/apache/cassandra-website/blob/master/README.md">here</a>.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <footer class="grad grad--two flex-center pb-xlarge"> |
| <div class="inner text-center z2 relative"> |
| <h2 class="white py-small">Get started with Cassandra, fast.</h2> |
| <a id="footer-cta" href="/_/quickstart.html" class="btn btn--filled ma-medium">Quickstart Guide</a> |
| </div> |
| <div class="inner flex flex-distribute-items mt-xlarge z2 relative"> |
| <div class="col-2"> |
| <div id="footer-logo" class="logo logo--footer mb-medium"><img src="../../assets/img/logo-white-r.png" alt="Cassandra Logo"></div> |
| <p>Apache Cassandra<img src="../../assets/img/registered.svg" alt="®" style="width:18px;"> powers mission-critical deployments with improved performance and unparalleled levels of scale in the cloud.</p> |
| <div class="footer-social-icons"> |
| <a href="https://twitter.com/cassandra?lang=en" target="_blank"><img src="../../assets/img/twitter-icon-circle-white.svg" alt="twitter icon" width="24"></a> |
| <a href="https://www.linkedin.com/company/apache-cassandra/" target="_blank"><img src="../../assets/img/LI-In-Bug.png" alt="linked-in icon" width="24"></a> |
| <a href="https://www.youtube.com/c/PlanetCassandra" target="_blank"><img src="../../assets/img/youtube-icon.png" alt="youtube icon" width="24"></a> |
| </div> |
| </div> |
| <div class="col-2 flex flex-center"> |
| <ul class="columns-2"> |
| <li class="mb-small"><a href="/">Home</a></li> |
| <li class="mb-small"><a href="/_/cassandra-basics.html">Cassandra Basics</a></li> |
| <li class="mb-small"><a href="/_/quickstart.html">Quickstart</a></li> |
| <li class="mb-small"><a href="/_/ecosystem.html">Ecosystem</a></li> |
| <li class="mb-small"><a href="/doc/latest/">Documentation</a></li> |
| <li class="mb-small"><a href="/_/community.html">Community</a></li> |
| <li class="mb-small"><a href="/_/case-studies.html">Case Studies</a></li> |
| <li class="mb-small"><a href="/_/resources.html">Resources</a></li> |
| <li class="mb-small"><a href="/_/blog.html">Blog</a></li> |
| </ul> |
| </div> |
| </div> |
| </footer> |
| <div class="lower-footer bg-white pa-medium"> |
| <div class="flex flex-row flex-vert-center"> |
| <div class="pr-medium"><img src="../../assets/img//feather-small.png" alt="ASF" width="20"></div> |
| <div class="pr-medium"><a href="http://www.apache.org/" target="_blank">Foundation</a></div> |
| <div class="pr-medium"><a href="https://www.apache.org/events/current-event.html" target="_blank">Events</a></div> |
| <div class="pr-medium"><a href="https://www.apache.org/licenses/" target="_blank">License</a></div> |
| <div class="pr-medium"><a href="https://www.apache.org/foundation/thanks" target="_blank">Thanks</a></div> |
| <div class="pr-medium"><a href="https://www.apache.org/security" target="_blank">Security</a></div> |
| <div class="pr-medium"><a href="https://privacy.apache.org/policies/privacy-policy-public.html" target="_blank">Privacy</a></div> |
| <div class="pr-medium"><a href="https://www.apache.org/foundation/sponsorship" target="_blank">Sponsorship</a></div> |
| </div> |
| <p class="my-medium">© 2009-<script>document.write(new Date().getFullYear())</script> <a href="https://apache.org" target="_blank">The Apache Software Foundation</a> under the terms of the Apache License 2.0. Apache, the Apache feather logo, Apache Cassandra, Cassandra, and the Cassandra logo, are either registered trademarks or trademarks of The Apache Software Foundation.</p> |
| </div> |
| <div id="fade" class="hidden"></div> |
| <div id="modal" class="hidden"> |
| <div id="close-modal" class="cursor-pointer"><svg viewBox="0 0 24 24" width="24" height="24" stroke="currentColor" stroke-width="2" fill="none" stroke-linecap="round" stroke-linejoin="round" class="css-i6dzq1"><line x1="18" y1="6" x2="6" y2="18"></line><line x1="6" y1="6" x2="18" y2="18"></line></svg></div> |
| <div id="mod-content" class="vid-mod-content resp-container"></div> |
| </div> |
| <script> |
| jQuery(function(){ |
| var windowW = $(window).width(); |
| $(document) |
| .on('click','.mobile-nav-icon',function(){ |
| $('.main-nav').fadeIn(); |
| }) |
| .on('click','.main-nav',function(){ |
| if(windowW <= 1000){ |
| $(this).fadeOut(); |
| } |
| }) |
| .on('click','#version-toggle',function(){ |
| $(this).toggleClass('active'); |
| $(this).next().fadeToggle(); |
| }) |
| .on('click','#mobile-docs-nav-burger', function(){ |
| $(this).toggleClass('active'); |
| $('.docs-nav').toggleClass('active'); |
| }); |
| var url = window.location.pathname; |
| var isQuickstart = url.includes('quickstart.html'); |
| if(isQuickstart){ |
| var footerCTA = document.getElementById('footer-cta'); |
| footerCTA.innerHTML = 'Get latest updates'; |
| footerCTA.setAttribute('href', '/_/blog.html'); |
| } |
| }); |
| </script> |
| </div> |
| </body> |
| <script> |
| jQuery(function(){ |
| jQuery(document) |
| .on('click','.cassandra-cloud h3',function(){ |
| var el = jQuery(this); |
| el.toggleClass('active'); |
| el.next().slideToggle(); |
| }) |
| .on('click','.image-expand img', function(){ |
| $(this).clone().appendTo('#mod-content'); |
| $('#fade,#modal,#close-modal').fadeIn(); |
| $('body,html').addClass('no-scroll'); |
| }) |
| .on('click','#fade,#close-modal', function(){ |
| $('#fade,#modal,#close-modal').fadeOut(); |
| $('body,html').removeClass('no-scroll'); |
| $('#mod-content').html(''); |
| }); |
| }); |
| </script> |
| </html> |
