Merge remote-tracking branch 'github/master'

CMakeLists.txt

@@ -13,6 +13,7 @@ IF (NOT TRIBITS_PROCESSING_PACKAGE)
   SET(${PROJECT_NAME}_TRIBITS_DIR "${CMAKE_CURRENT_SOURCE_DIR}/tribits" CACHE PATH "")
   INCLUDE("${${PROJECT_NAME}_TRIBITS_DIR}/TriBITS.cmake")
   SET(${PROJECT_NAME}_ENABLE_TESTS ON CACHE BOOL "Enable tests by default.")
+  INCLUDE("${CMAKE_CURRENT_SOURCE_DIR}/cmake/AssertSameVersionFile.cmake")
   TRIBITS_PROJECT_ENABLE_ALL()
 ELSE()
   # This CMakeLists.txt file is being processed as the TriBITS package file.

CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# Contributing to TriBITS
+
+**Contents:**
+* [Requirements for every change to TriBITS](#requirements)
+* [Preferred process for suggesting and making changes to TriBITS](#process):
+  * [Process Outline](#process_outline)
+  * [Process Details](#process_details)
+
+Contributions to TriBITS are welcomed.  However, there are some [requirements](#requirements) that every contribution needs to follow before it can be integrated into the main development branch of TriBITS and there is a [recommended process](#process) for suggesting and submitted proposed changes.
+
+**NOTE:** All contributions that are submitted are assumed to be given under the **[3-clause BSD-like TriBITS License](https://github.com/TriBITSPub/TriBITS/blob/master/tribits/Copyright.txt).**
+
+<a name="requirements"/>
+
+## Requirements for every change to TriBITS
+
+1. **Automated Tests:** Any change in behavior or new behavior needs to be accompanied with automated tests to define and protect these changes.  If automated tests are not possible or too difficult, this can be discussed in the Github Issue or Pull-Request (see below).
+2. **GitHub Issue:** All non-trivial changes should have a [GitHub Issue created](#process_create_issue) for them and all associated commits should list the GitHub Issue ID in the commit logs.
+3. **Documentation:** Any new feature or change in the behavior of an existing feature must be fully documented before it is accepted.  This documentation is generally added to one or more of the following places:
+   * Implementation `*.cmake` file itself (formatted with restructuredText and pulled out automatically into the TriBITS Developers Guide, see existing examples)
+   * `TribitsDevelopersGuide.rst` document (under `tribits/doc/developers_guide/`)
+   * `TribitsBuildReferenceBody.rst` document (under `tribits/doc/build_ref/`)
+
+<a name="process">
+
+## Preferred process for suggesting and making changes to TriBITS
+
+<a name="process_outline">
+
+### Process Outline
+
+The steps in the preferred process for making changes to TriBITS are:
+
+1. [Create GitHub Issue](#process_create_issue) (communicate about the requirements and design)
+2. [Create Pull-Request](#process_create_pull_request) (each commit references the GitHub Issue ID)
+3. [Perform Code Review](#process_code_review) (perhaps adding new commits to address issues)
+4. [Accept Pull-Request](#process_accept_pull_request) (merge/rebase and push the branch to 'master')
+
+The details are given in the next section.
+
+<a name="process_details"/>
+
+### Process Details
+
+The following roles are mentioned on the process descriptions:
+* **TriBITS Maintainer**: Individual with push rights to the main TriBITS repo (i.e. Ross Bartlett).  Must review all issues and suggested changes and accept pull-requests.
+* **TriBITS Developer**: Someone who knows how to built TriBITS as a project with its tests, add tests, make acceptable changes, create pull-requests, etc. but can't directly push to the main TriBITS github 'master' branch (see the role of [TriBITS System Developer](https://tribits.org/doc/TribitsDevelopersGuide.html#tribits-developer-and-user-roles)).  This might be the Issue Reporter.
+* **Issue Reporter**: A person who first reports an issue with TriBITS and would like some type of change to happen (i.e. to fix a defect, implement a new feature, etc.).  This might be a TriBITS Developer.
+
+With those definitions in place, the recommended/preferred process for contributing to TriBITS is:
+
+<a name="process_create_issue"/>
+
+1. **Create GitHub Issue:** The Issue Reporter should submit a [GitHub Issue](https://github.com/TriBITSPub/TriBITS/issues) proposing the change (see [Kanban Process](https://github.com/TriBITSPub/TriBITS/wiki/Kanban-Process-for-Issue-Tracking) used to manage TriBITS Issues).  That way, a conversation can be started to make sure the right contribution is made and to avoid wasted effort in case a suggested change can't be accepted for some reason.  **If the TriBITS Maintainer decides that the proposed change is not appropriate, then the Issue may be closed after the justification is added to a comment.**  Also, the TriBITS Maintainer may offer to implement the changes themselves or ask another TriBITS Developer to do so if that is most appropriate.  However, regardless of who actually makes the proposed changes, the following steps should is still be followed.
+
+<a name="process_create_pull_request"/>
+
+2. **Create Pull-Request:** After the proposed change is approved in the GitHub Issue by the TriBITS Maintainer, then the TriBITS Developer (who might be the Issue Reporter or the TriBITS Maintainer) should create a Pull-Request performing the following steps:
+    * **create a topic/feature branch** in their forked TriBITS repo (use descriptive branch name with issue ID, e.g. `some-great-feature-123`) ,
+    * **create commits with logs referencing the Issue ID** (e.g. `fix that thing (#123)`),
+    * **issue a [pull-request](https://help.github.com/articles/using-pull-requests/) (i.e. PR)**.
+    * The changes in the PR will automatically be tested using [Travis CI](https://travis-ci.org/TriBITSPub/TriBITS).  Also, the PR allows for a well managed code review (comments for each line of the change, for example).  The pull request should then reference the original GitHub Issue in a comment to link the PR to the original Issue.  (NOTE: A partial set of changes is just fine in the PR, just enough to start the code review process.)
+    * NOTE: The TriBITS Maintainers should be given push access to the topic-branch used to create the PR.  That way, the contributors, TriBITS Developers and the TriBITS Maintainer can all push new commits to that branch in a more collaborative way and have the PR Issue get updated automatically.
+
+<a name="process_code_review"/>
+
+3. **Perform Code Review:** A code review process is performed by the TriBITS Maintainer and continued changes are made by the TriBITS Developer and comments are added to the new PR or the original Issue (whatever makes sense but usually comments specific to changes should be added to the PR while more general comments not specific to the PR should go into the associated GitHub Issue).  New updates to the branch can be pushed by the TriBITS Developer as changes are made to address issues with the changes.  (And if the topic branch is pushed to the main GitHub repo, then multiple developers can push commits as well.)
+
+<a name="process_accept_pull_request"/>
+
+4. **Accept Pull-Request:** The TriBITS maintainer will then either accept the PR (by rebasing and merging the branch to main development branch) or will state what further issues must be resolved before the change can be incorporated.
+
+**NOTE:** Very simple changes can be attached to a GitHub Issue which are generated using `git format-patch` but the above process involving pull requests is preferred.  But **generally raw patches will not be accepted** due to the added difficulty for the TriBITS Maintainer to review the changes and to eventually apply them to the TriBITS 'master' branch itself.  Also, using git commits sent either through a branch in a pull-request or through `git format-patch` will record the author's contribution and give them credit for the change. 
+
+**NOTE:** The above process is just a suggested process.  What is important are the [requirements](#requirements) listed above.

README.DIRECTORY_CONTENTS.rst

@@ -5,7 +5,7 @@ This base directory for TriBITS acts as a TriBITS Project, a TriBITS
 Repository, and a TriBITS Package.  As such, it contains the standard files
 that are found in a TriBITS Project, Repository, and Package::
 
-  ProjectName.cmake   # PROJECT_NAME=TriITS
+  ProjectName.cmake   # PROJECT_NAME=TriBITS
   CMakeLists.txt      # PROJECT_NAME = PACKAGE_NAME = TriBITS
   PackagesList.cmake  # Lists just "TriBITS . PT"
   TPLsList.cmake      # Lists only MPI

README.rst

@@ -57,30 +57,30 @@ To set up to develop on TriBITS:
     $ make
     $ ctest -j12
 
-  NOTES:
+NOTES:
 
-  * If you don't have a working and compatible Fortran compiler, then pass
-    ``-DTriBITS_ENABLE_Fortran=OFF`` into the ``do-configure`` script as::
+* If you don't have a working and compatible Fortran compiler, then pass
+  ``-DTriBITS_ENABLE_Fortran=OFF`` into the ``do-configure`` script as::
 
-      $ ./do-configure -DTriBITS_ENABLE_Fortran=OFF
+    $ ./do-configure -DTriBITS_ENABLE_Fortran=OFF
 
-  * On Mac OSX systems, one has to manually set the path the the TriBITS
-    project base dir TRIBITS_BASE_DIR such as with::
+* On Mac OSX systems, one has to manually set the path the the TriBITS
+  project base dir TRIBITS_BASE_DIR such as with::
 
-      $ env TRIBITS_BASE_DIR=.. ./do-configure [other options]
+    $ env TRIBITS_BASE_DIR=.. ./do-configure [other options]
 
-  * Use as many processes as you have with ``ctest`` (``-j12`` is just used as
-    an example).
+* Use as many processes as you have with ``ctest`` (``-j12`` is just used as
+  an example).
 
-  * All of the tests should pass on your machine before beginning any
-    development work.  If there are any failures, then please `report them`_.
-    To help show the failures you are seeing, do::
+* All of the tests should pass on your machine before beginning any
+  development work.  If there are any failures, then please `report them`_.
+  To help show the failures you are seeing, do::
 
-      $ ./do-configure -DCTEST_PARALLEL_LEVEL=12
-      $ make dashboard
+  $ ./do-configure -DCTEST_PARALLEL_LEVEL=12
+  $ make dashboard
 
-    and then provide the link to the CDash results in the TriBITS Issue when
-    you report them.
+  and then provide the link to the CDash results in the TriBITS Issue when
+  you report them.
 
 Any change (refactoring) of TriBITS (minimally) requires that the automated
 test suite run with ``ctest`` pass 100%.  To add new features (in most cases)

Version.cmake

@@ -0,0 +1,9 @@
+IF ("${REPOSITORY_NAME}" STREQUAL "")
+  SET(REPOSITORY_NAME TriBITS)
+ENDIF()
+
+SET(${REPOSITORY_NAME}_VERSION 0.9)
+SET(${REPOSITORY_NAME}_MAJOR_VERSION 00)
+SET(${REPOSITORY_NAME}_MAJOR_MINOR_VERSION 000900)
+SET(${REPOSITORY_NAME}_VERSION_STRING "0.9 (Dev)")
+SET(${REPOSITORY_NAME}_ENABLE_DEVELOPMENT_MODE_DEFAULT ON) # Change to 'OFF' for a release

cmake/AssertSameVersionFile.cmake

@@ -0,0 +1,13 @@
+# Make sure the base Version.cmake file is the same as the copy in
+# tribits/Version.cmake We can't use a symlink because this breaks TriBITS on
+# Windows (See TriBITSPub/TriBITS#129).  Later, this will be replaced with a
+# configured Version.cmake file so this will not be an issue.
+SET(BASE_VERSION_CMAKE_FILE "${CMAKE_CURRENT_SOURCE_DIR}/Version.cmake")
+SET(TRIBITS_VERSION_CMAKE_FILE "${CMAKE_CURRENT_SOURCE_DIR}/tribits/Version.cmake")
+FILE(READ "${BASE_VERSION_CMAKE_FILE}" BASE_VERSION_CMAKE_STR)
+FILE(READ "${TRIBITS_VERSION_CMAKE_FILE}" TRIBITS_VERSION_CMAKE_STR)
+IF (NOT BASE_VERSION_CMAKE_STR STREQUAL TRIBITS_VERSION_CMAKE_STR)
+  MESSAGE(FATAL_ERROR
+    "ERROR: '${BASE_VERSION_CMAKE_FILE}' and '${TRIBITS_VERSION_CMAKE_FILE}' are"
+    " different (see TriBITSPub/TriBITS#129)!")
+ENDIF()

cmake/ctest/travisci/ctest_trusty_serial_debug.cmake

@@ -18,6 +18,7 @@ INCLUDE("${CMAKE_CURRENT_LIST_DIR}/../../../tribits/ctest_driver/TribitsCTestDri
 SET(COMM_TYPE SERIAL)
 SET(BUILD_TYPE DEBUG)
 SET(BUILD_DIR_NAME ${COMM_TYPE}_${BUILD_TYPE}_TravisCI)
+SET(CTEST_SITE TravisCI)
 #SET(CTEST_TEST_TIMEOUT 900)
 
 SET_DEFAULT_AND_FROM_ENV( CTEST_BUILD_FLAGS "-j1 -i" )

dev_testing/crf450/checkin-test-crf450.sh → dev_testing/crf450/checkin-test-crf450-cmake-2.8.11.sh

@@ -1,14 +1,6 @@
 #!/bin/bash
 
-# Used to test TriBITS on any the machine crf450 using the VERA Dev Env
-#
-# This script requires that the VERA dev env be loaded by sourcing the script:
-#
-#  . /home/vera_env/gcc-4.8.3/load_dev_env.[sh,csh]
-#
-# You can source this script either in your shell startup script
-# (e.g. .bash_profile) or you can source it manually whenever you need to set
-# up to build VERA software.
+# Used to test TriBITS on crf450 using the VERA Dev Env using CMake 2.8.11
 #
 # You can link this script into any location and it will work out of the box.
 #
@@ -22,11 +14,9 @@ fi
 TRIBITS_BASE_DIR_ABS=$(readlink -f $TRIBITS_BASE_DIR)
 #echo "TRIBITS_BASE_DIR_ABS = $TRIBITS_BASE_DIR_ABS"
 
-# Check to make sure that the env has been loaded correctly
-if [ "$LOADED_TRIBITS_DEV_ENV" != "gcc-4.8.3" ] ; then
-  echo "Error, must source /home/vera_env/gcc-4.8.3/load_dev_env.[sh,csh] before running checkin-test-vera.sh!"
-  exit 1
-fi
+# Load the env:
+source /home/vera_env/gcc-4.8.3/load_dev_env.sh
+export PATH=/home/vera_env/common_tools/cmake-2.8.11/bin:$PATH
 
 # Create local defaults file if one does not exist
 _LOCAL_CHECKIN_TEST_DEFAULTS=local-checkin-test-defaults.py
@@ -41,9 +31,6 @@ defaults = [
   " > $_LOCAL_CHECKIN_TEST_DEFAULTS
 fi
 
-# Use CMake 2.8.11 to test since that is the min version we are enforcing!
-export PATH=/home/vera_dev/common_tools/cmake-2.8.11/bin:$PATH
-
 $TRIBITS_BASE_DIR_ABS/checkin-test.py \
 --extra-cmake-options="-DPYTHON_EXECUTABLE=/usr/bin/python2.6" \
 --ctest-timeout=180 \

dev_testing/crf450/checkin-test-crf450-cmake-3.6.2.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+
+# Used to test TriBITS on crf450 using the VERA Dev Env with CMake 3.6.2.
+#
+# You can link this script into any location and it will work out of the box.
+#
+
+if [ "$TRIBITS_BASE_DIR" == "" ] ; then
+  _ABS_FILE_PATH=`readlink -f $0`
+  _SCRIPT_DIR=`dirname $_ABS_FILE_PATH`
+  TRIBITS_BASE_DIR=$_SCRIPT_DIR/../..
+fi
+
+TRIBITS_BASE_DIR_ABS=$(readlink -f $TRIBITS_BASE_DIR)
+#echo "TRIBITS_BASE_DIR_ABS = $TRIBITS_BASE_DIR_ABS"
+
+# Load the env:
+source /home/vera_env/gcc-4.8.3/load_dev_env.sh
+export PATH=/home/vera_env/common_tools/cmake-3.6.2/bin:$PATH
+
+# Create extra builds run by this script
+
+echo "
+-DTPL_ENABLE_MPI:BOOL=ON
+-DCMAKE_BUILD_TYPE:STRING=DEBUG
+-DTriBITS_ENABLE_DEBUG:BOOL=ON
+-DTriBITS_ENABLE_Fortran:BOOL=ON
+" > MPI_DEBUG_CMAKE-3.6.2.config
+
+echo "
+-DTPL_ENABLE_MPI:BOOL=OFF
+-DCMAKE_BUILD_TYPE:STRING=RELEASE
+-DTriBITS_ENABLE_DEBUG:BOOL=OFF
+-DCMAKE_C_COMPILER=gcc
+-DCMAKE_CXX_COMPILER=g++
+-DCMAKE_Fortran_COMPILER=gfortran
+" > SERIAL_RELEASE_CMAKE-3.6.2.config
+
+# Run checkin-test.py
+
+$TRIBITS_BASE_DIR_ABS/checkin-test.py \
+--extra-cmake-options="-DPYTHON_EXECUTABLE=/usr/bin/python2.6" \
+--default-builds= \
+--st-extra-builds=MPI_DEBUG_CMAKE-3.6.2,SERIAL_RELEASE_CMAKE-3.6.2 \
+--ctest-timeout=180 \
+--skip-case-no-email \
+"$@"

dev_testing/crf450/checkin-test-crf450-do-all-push.sh

@@ -0,0 +1,81 @@
+#!/bin/bash
+# 
+# Used to test and push TriBITS on crf450 using the VERA Dev Env with CMake
+# 3.8.11 and CMake 3.6.2.
+#
+# Unlike regular checkin-tset.py drivers, this script is hard-coded with
+# --do-all --push and does not accept any other arguments.  To use this, you
+# need to also symlink in the scripts checkin-test-crf450-cmake-2.8.11.sh
+# checkin-test-crf450-cmake-3.6.2.sh then run as:
+#
+#   $ ./checkin-test-crf450-cmake-3.6.2.sh
+#
+# WARNING: This does the --push as well so make sure you want to do that!
+#
+# You can skip the push by running with:
+#
+#   $ env CHECKIN_TEST_CRF450_SKIP_PUSH=1 ./checkin-test-crf450-cmake-3.6.2.sh
+#
+# You can also just do a local test with:
+#
+#   $ env CHECKIN_TEST_CRF450_SKIP_PUSH=1 \
+#      CHECKIN_TEST_CRF450_LOCAL_DO_ALL=1 \
+#      ./checkin-test-crf450-cmake-3.6.2.sh
+#
+# This script does not send out any email except for the final checkin-test.py
+# --push command.
+#
+# NOTE: This script is NOT run with 'bash -e' so failures in the individual
+# checkin-test calls are ignored until the final checkin-test.py script is
+# called.  But that final checkin-test.py script will not push unless all of
+# the listed builds all passed.
+#
+
+if [ "$TRIBITS_BASE_DIR" == "" ] ; then
+  _ABS_FILE_PATH=`readlink -f $0`
+  _SCRIPT_DIR=`dirname $_ABS_FILE_PATH`
+  TRIBITS_BASE_DIR=$_SCRIPT_DIR/../..
+fi
+
+TRIBITS_BASE_DIR_ABS=$(readlink -f $TRIBITS_BASE_DIR)
+#echo "TRIBITS_BASE_DIR_ABS = $TRIBITS_BASE_DIR_ABS"
+
+if [ "$CHECKIN_TEST_CRF450_LOCAL_DO_ALL" == "1" ] ; then
+  CHECKIN_TEST_1_DO_ALL_ARG=--local-do-all
+  CHECKIN_TEST_2_ALLOW_NO_PULL_ARG=--allow-no-pull
+else
+  CHECKIN_TEST_1_DO_ALL_ARG=--do-all
+  CHECKIN_TEST_2_ALLOW_NO_PULL_ARG=
+fi
+
+if [ "$CHECKIN_TEST_CRF450_SKIP_PUSH" == "1" ] ; then
+  CHECKIN_TEST_PUSH_ARG=
+else
+  CHECKIN_TEST_PUSH_ARG=--push
+fi
+
+echo
+echo "***"
+echo "*** A) Running checkin-test-crf450-cmake-2.8.11.sh $CHECKIN_TEST_1_DO_ALL_ARG --send-email-to= ..."
+echo "***"
+echo
+
+./checkin-test-crf450-cmake-2.8.11.sh $CHECKIN_TEST_1_DO_ALL_ARG --send-email-to=
+
+echo
+echo "***"
+echo "*** B) Running checkin-test-crf450-cmake-3.6.2.sh $CHECKIN_TEST_2_ALLOW_NO_PULL_ARG --configure --build --test --send-email-to= ..."
+echo "***"
+echo
+
+./checkin-test-crf450-cmake-3.6.2.sh $CHECKIN_TEST_2_ALLOW_NO_PULL_ARG --configure --build --test --send-email-to=
+
+echo
+echo "***"
+echo "*** C) Running checkin-test.py [all the builds] --no-rebase $CHECKIN_TEST_PUSH_ARG ..."
+echo "***"
+echo
+
+$TRIBITS_BASE_DIR_ABS/checkin-test.py \
+--st-extra-builds=MPI_DEBUG_CMAKE-3.6.2,SERIAL_RELEASE_CMAKE-3.6.2 \
+--no-rebase $CHECKIN_TEST_PUSH_ARG