Repository: cassandra Updated Branches: refs/heads/trunk 7583c9b96 -> 01ade6f25
Docs: add Jenkins setup details patch by Stefan Podkowinski; reviewed by Michael Shuler for CASSANDRA-13534 Project: http://git-wip-us.apache.org/repos/asf/cassandra/repo Commit: http://git-wip-us.apache.org/repos/asf/cassandra/commit/01ade6f2 Tree: http://git-wip-us.apache.org/repos/asf/cassandra/tree/01ade6f2 Diff: http://git-wip-us.apache.org/repos/asf/cassandra/diff/01ade6f2 Branch: refs/heads/trunk Commit: 01ade6f251314a7a438f6398f4fad95a6b5eb8b3 Parents: 7583c9b Author: Stefan Podkowinski <[email protected]> Authored: Tue May 16 21:12:08 2017 +0200 Committer: Stefan Podkowinski <[email protected]> Committed: Tue May 16 23:07:12 2017 +0200 ---------------------------------------------------------------------- doc/source/development/ci.rst | 72 +++++++++++++++++++++++++++++++++ doc/source/development/ide.rst | 4 -- doc/source/development/index.rst | 1 + doc/source/development/patches.rst | 2 +- doc/source/development/testing.rst | 2 +- 5 files changed, 75 insertions(+), 6 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cassandra/blob/01ade6f2/doc/source/development/ci.rst ---------------------------------------------------------------------- diff --git a/doc/source/development/ci.rst b/doc/source/development/ci.rst new file mode 100644 index 0000000..192b188 --- /dev/null +++ b/doc/source/development/ci.rst @@ -0,0 +1,72 @@ +.. Licensed to the Apache Software Foundation (ASF) under one +.. or more contributor license agreements. See the NOTICE file +.. distributed with this work for additional information +.. regarding copyright ownership. The ASF licenses this file +.. to you under the Apache License, Version 2.0 (the +.. "License"); you may not use this file except in compliance +.. with the License. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. + +Jenkins CI Environment +********************** + +About CI testing and Apache Cassandra +===================================== + +Cassandra can be automatically tested using various test suites, that are either implemented based on JUnit or the `dtest <https://github.com/riptano/cassandra-dtest>`_ scripts written in Python. As outlined in :doc:`testing`, each kind of test suite addresses a different way how to test Cassandra. But in the end, all of them will be executed together on our CI platform at `builds.apache.org <https://builds.apache.org>`_, running `Jenkins <http://jenkins-ci.org>`_. + + + +Setting up your own Jenkins server +================================== + +Jenkins is an open source solution that can be installed on a large number of platforms. Setting up a custom Jenkins instance for Cassandra may be desirable for users who have hardware to spare, or organizations that want to run Cassandra tests for custom patches before contribution. + +Please refer to the Jenkins download and documentation pages for details on how to get Jenkins running, possibly also including slave build executor instances. The rest of the document will focus on how to setup Cassandra jobs in your Jenkins environment. + +Required plugins +---------------- + +The following plugins need to be installed additionally to the standard plugins (git, ant, ..). + +You can install any missing plugins through the install manager. + +Go to ``Manage Jenkins -> Manage Plugins -> Available`` and install the following plugins and respective dependencies: + +* Job DSL +* Javadoc Plugin +* description setter plugin +* Throttle Concurrent Builds Plug-in +* Test stability history +* Hudson Post build task + + +Setup seed job +-------------- + +Config ``New Item`` + +* Name it ``Cassandra-Job-DSL`` +* Select ``Freestyle project`` + +Under ``Source Code Management`` select Git using the repository: ``https://github.com/apache/cassandra-builds`` + +Under ``Build``, confirm ``Add build step`` -> ``Process Job DSLs`` and enter at ``Look on Filesystem``: ``jenkins-dsl/cassandra_job_dsl_seed.groovy`` + +Generated jobs will be created based on the Groovy script's default settings. You may want to override settings by checking ``This project is parameterized`` and add ``String Parameter`` for on the variables that can be found in the top of the script. This will allow you to setup jobs for your own repository and branches (e.g. working branches). + +**When done, confirm "Save"** + +You should now find a new entry with the given name in your project list. However, building the project will still fail and abort with an error message `"Processing DSL script cassandra_job_dsl_seed.groovy ERROR: script not yet approved for use"`. Goto ``Manage Jenkins`` -> ``In-process Script Approval`` to fix this issue. Afterwards you should be able to run the script and have it generate numerous new jobs based on the found branches and configured templates. + +Jobs are triggered by either changes in Git or are scheduled to execute periodically, e.g. on daily basis. Jenkins will use any available executor with the label "cassandra", once the job is to be run. Please make sure to make any executors available by selecting ``Build Executor Status`` -> ``Configure`` -> Add "``cassandra``" as label and save. + + + http://git-wip-us.apache.org/repos/asf/cassandra/blob/01ade6f2/doc/source/development/ide.rst ---------------------------------------------------------------------- diff --git a/doc/source/development/ide.rst b/doc/source/development/ide.rst index 2986495..c52c11a 100644 --- a/doc/source/development/ide.rst +++ b/doc/source/development/ide.rst @@ -42,10 +42,6 @@ This may take a significant amount of time depending on whether artifacts have t You can setup multiple working trees for different Cassandra versions from the same repository using `git-worktree <https://git-scm.com/docs/git-worktree>`_. -.. note:: - - `Bleeding edge development snapshots <http://cassci.datastax.com/job/trunk/lastSuccessfulBuild/>`_ of Cassandra are available from Jenkins continuous integration. - Setting up Cassandra in IntelliJ IDEA ===================================== http://git-wip-us.apache.org/repos/asf/cassandra/blob/01ade6f2/doc/source/development/index.rst ---------------------------------------------------------------------- diff --git a/doc/source/development/index.rst b/doc/source/development/index.rst index a09c945..33de8ee 100644 --- a/doc/source/development/index.rst +++ b/doc/source/development/index.rst @@ -28,3 +28,4 @@ Contributing to Cassandra how_to_review how_to_commit documentation + ci http://git-wip-us.apache.org/repos/asf/cassandra/blob/01ade6f2/doc/source/development/patches.rst ---------------------------------------------------------------------- diff --git a/doc/source/development/patches.rst b/doc/source/development/patches.rst index d3dd198..3bab5d0 100644 --- a/doc/source/development/patches.rst +++ b/doc/source/development/patches.rst @@ -93,7 +93,7 @@ So you've finished coding and the great moment arrives: it's time to submit your 1. Create a branch for your changes if you haven't done already. Many contributors name their branches based on ticket number and Cassandra version, e.g. ``git checkout -b 12345-3.0`` 2. Verify that you follow Cassandra's :doc:`code_style` - 3. Make sure all tests (including yours) pass using ant as described in :doc:`testing`. If you suspect a test failure is unrelated to your change, it may be useful to check the test's status by searching the issue tracker or looking at `CI <https://cassci.datastax.com/>`_ results for the relevant upstream version. Note that the full test suites take many hours to complete, so it is common to only run specific relevant tests locally before uploading a patch. Once a patch has been uploaded, the reviewer or committer can help setup CI jobs to run the full test suites. + 3. Make sure all tests (including yours) pass using ant as described in :doc:`testing`. If you suspect a test failure is unrelated to your change, it may be useful to check the test's status by searching the issue tracker or looking at `CI <https://builds.apache.org/>`_ results for the relevant upstream version. Note that the full test suites take many hours to complete, so it is common to only run specific relevant tests locally before uploading a patch. Once a patch has been uploaded, the reviewer or committer can help setup CI jobs to run the full test suites. 4. Consider going through the :doc:`how_to_review` for your code. This will help you to understand how others will consider your change for inclusion. 5. Donât make the committer squash commits for you in the root branch either. Multiple commits are fine - and often preferable - during review stage, especially for incremental review, but once +1d, do either: http://git-wip-us.apache.org/repos/asf/cassandra/blob/01ade6f2/doc/source/development/testing.rst ---------------------------------------------------------------------- diff --git a/doc/source/development/testing.rst b/doc/source/development/testing.rst index 1e4d46a..ca8b538 100644 --- a/doc/source/development/testing.rst +++ b/doc/source/development/testing.rst @@ -62,7 +62,7 @@ DTests One way of doing integration or system testing at larger scale is by using `dtest <https://github.com/riptano/cassandra-dtest>`_, which stands for âCassandra Distributed Testsâ. The idea is to automatically setup Cassandra clusters using various configurations and simulate certain use cases you want to test. This is done using Python scripts and ``ccmlib`` from the `ccm <https://github.com/pcmanus/ccm>`_ project. Dtests will setup clusters using this library just as you do running ad-hoc ``ccm`` commands on your local machine. Afterwards dtests will use the `Python driver <http://datastax.github.io/python-driver/installation.html>`_ to interact with the nodes, manipulate the file system, analyze logs or mess with individual nodes. -Using dtests helps us to prevent regression bugs by continually executing tests on the `CI server <http://cassci.datastax.com/>`_ against new patches. For frequent contributors, this Jenkins is set up to build branches from their GitHub repositories. It is likely that your reviewer will use this Jenkins instance to run tests for your patch. Read more on the motivation behind the CI server `here <http://www.datastax.com/dev/blog/cassandra-testing-improvements-for-developer-convenience-and-confidence>`_. +Using dtests helps us to prevent regression bugs by continually executing tests on the `CI server <https://builds.apache.org/>`_ against new patches. Committers will be able to set up build branches there and your reviewer may use the CI environment to run tests for your patch. Read more on the motivation behind continuous integration `here <http://www.datastax.com/dev/blog/cassandra-testing-improvements-for-developer-convenience-and-confidence>`_. The best way to learn how to write dtests is probably by reading the introduction "`How to Write a Dtest <http://www.datastax.com/dev/blog/how-to-write-a-dtest>`_" and by looking at existing, recently updated tests in the project. New tests must follow certain `style conventions <https://github.com/riptano/cassandra-dtest/blob/master/CONTRIBUTING.md>`_ that are being checked before accepting contributions. In contrast to Cassandra, dtest issues and pull-requests are managed on github, therefor you should make sure to link any created dtests in your Cassandra ticket and also refer to the ticket number in your dtest PR. --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
