Merge pull request #69 from cicirello/development

Updates to build process, CI/CD, workflows, etc

Author: cicirello

.github/dependabot.yml

@@ -7,11 +7,11 @@ version: 2
 updates:
   - package-ecosystem: "maven" # See documentation for possible values
     directory: "/" # Location of package manifests
-    target-branch: "development"
+    target-branch: "master"
     schedule:
       interval: "daily"
   - package-ecosystem: "github-actions" # See documentation for possible values
     directory: "/" # Location of package manifests
-    target-branch: "development"
+    target-branch: "master"
     schedule:
       interval: "daily"

.github/workflows/ant.yml

@@ -0,0 +1,53 @@
+name: build
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up JDK 1.11
+      uses: actions/setup-java@v1
+      with:
+        java-version: 1.11
+
+    - name: Build with Maven
+      run: mvn -B package -Pcoverage
+
+    - name: Generate Jacoco Badge
+      id: jacoco
+      uses: cicirello/[email protected]
+
+    - name: Log coverage percentage
+      run: |
+        echo "coverage = ${{ steps.jacoco.outputs.coverage }}"
+
+    - name: Create pull request
+      if: ${{ github.event_name == 'push' }}
+      uses: peter-evans/[email protected]
+      with:
+        title: "Autogenerated Jacoco Coverage Badge"
+        body: > 
+          Autogenerated Jacoco coverage badge, generated by 
+          the [jacoco-badge-generator](https://github.com/cicirello/jacoco-badge-generator) 
+          GitHub action.  Automated pull-request generated by 
+          [create-pull-request](https://github.com/peter-evans/create-pull-request) 
+          GitHub action.
+        commit-message: "Autogenerated Jacoco Coverage Badge"
+        author: Vincent A Cicirello <[email protected]>
+        committer: Vincent A Cicirello <[email protected]>
+        branch: create-pull-request/badge
+        delete-branch: true
+
+    - name: Upload Jacoco coverage report
+      uses: actions/upload-artifact@v2
+      with:
+        name: jacoco-report
+        path: target/site/jacoco/

.github/workflows/build.yml

@@ -2,11 +2,14 @@ name: docs
 
 on:
   push:
-    branches: [ development ]
+    branches: [ master ]
+    paths: [ '**.java' ]
+  pull_request:
+    branches: [ master ]
     paths: [ '**.java' ]
 
 jobs:
-  api-website:
+  docs:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout the repo
@@ -18,38 +21,29 @@ jobs:
       uses: actions/setup-java@v1
       with:
         java-version: 1.11
-    
-    - name: Clean docs
-      run: ant -noinput -buildfile build/builddocs.xml clean
 
-    - name: Build docs with Ant
-      run: ant -noinput -buildfile build/builddocs.xml
-    
+    - name: Build docs with Maven
+      run: mvn javadoc:javadoc
+
+    - name: Copy to Documentation Website Location
+      run: |
+        rm -rf docs/api
+        cp -rf target/site/apidocs/. docs/api	
+
     - name: Tidy up the javadocs
       id: tidy
       uses: cicirello/[email protected]
       with:
-        path-to-root: docs
         base-url-path: https://jpt.cicirello.org/
-    
+        path-to-root: docs
+
     - name: Log javadoc-cleanup output
       run: |
         echo "modified-count = ${{ steps.tidy.outputs.modified-count }}"
-    
+
     - name: Commit documentation changes
       run: |
-        if [ $(git status | grep -c "**/*.html") == "0" ]; then
-          git checkout .
-        else
-          if [ $(git status | grep -c "**/member-search-index.*") == "1" ]; then
-            git checkout -- docs/api/member-search-index.zip
-          fi
-          if [ $(git status | grep -c "**/package-search-index.*") == "1" ]; then
-            git checkout -- docs/api/package-search-index.zip
-          fi
-          if [ $(git status | grep -c "**/type-search-index.*") == "1" ]; then
-            git checkout -- docs/api/type-search-index.zip
-          fi
+        if [[ `git status --porcelain` ]]; then
           git config --global user.name 'Vincent A Cicirello'
           git config --global user.email '[email protected]'
           git add -A
@@ -70,7 +64,8 @@ jobs:
         echo "excluded-count = ${{ steps.sitemap.outputs.excluded-count }}"
 
     - name: Create Pull Request
-      uses: peter-evans/[email protected]
+      if: ${{ github.event_name == 'push' }}
+      uses: peter-evans/[email protected]
       with:
         title: "Automated API website updates."
         body: > 
@@ -83,5 +78,5 @@ jobs:
         commit-message: "Automated API documentation website updates."
         author: Vincent A Cicirello <[email protected]>
         committer: Vincent A Cicirello <[email protected]>
+        branch: create-pull-request/docs
         delete-branch: true
-

.github/workflows/api-website.yml .github/workflows/docs.yml.github/workflows/api-website.yml renamed to .github/workflows/docs.yml

@@ -66,7 +66,7 @@ jobs:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       with:
         upload_url: ${{ steps.get.outputs.upload_url }} 
-        asset_path: dist/${{ env.artifact_name }}-${{ steps.get_version.outputs.VERSION }}.jar
+        asset_path: target/${{ env.artifact_name }}-${{ steps.get_version.outputs.VERSION }}.jar
         asset_name: ${{ env.artifact_name }}-${{ steps.get_version.outputs.VERSION }}.jar
         asset_content_type: application/java-archive
 
@@ -77,7 +77,7 @@ jobs:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       with:
         upload_url: ${{ steps.get.outputs.upload_url }} 
-        asset_path: dist/${{ env.artifact_name }}-${{ steps.get_version.outputs.VERSION }}-sources.jar
+        asset_path: target/${{ env.artifact_name }}-${{ steps.get_version.outputs.VERSION }}-sources.jar
         asset_name: ${{ env.artifact_name }}-${{ steps.get_version.outputs.VERSION }}-sources.jar
         asset_content_type: application/java-archive
 
@@ -88,6 +88,6 @@ jobs:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       with:
         upload_url: ${{ steps.get.outputs.upload_url }} 
-        asset_path: dist/${{ env.artifact_name }}-${{ steps.get_version.outputs.VERSION }}-javadoc.jar
+        asset_path: target/${{ env.artifact_name }}-${{ steps.get_version.outputs.VERSION }}-javadoc.jar
         asset_name: ${{ env.artifact_name }}-${{ steps.get_version.outputs.VERSION }}-javadoc.jar
         asset_content_type: application/java-archive

.github/workflows/maven-publish.yml

@@ -1,3 +1,9 @@
 bin/
 exbin/
 testbin/
+target/
+member-search-index.zip
+type-search-index.zip
+package-search-index.zip
+module-search-index.zip
+tag-search-index.zip

.gitignore

@@ -4,7 +4,8 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased] - 2020-09-22
+## [Unreleased] - 2021-01-27
+
 ### Added
 
 ### Changed
@@ -13,9 +14,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Deprecated
 
 ### Removed
+* Moved the example programs to a new repository. They were previously found in directories examples and replication, both of which have been removed. All of the examples are now located in the repository: https://github.com/cicirello/jpt-examples.
+* Removed jars of the library from the repo. These have been available from Maven Central, GitHub Packages, and GitHub Releases, for quite some time. No need to store in repo, and it is inefficient to do so.
+* Removed the zip files generated by javadoc of the indexes for the api website. These are not needed for search functionality, as javadoc also stores and uses the js files contained in these zips. Later versions of javadoc no longer generate these. Also gitignored these to prevent future storage.
 
 ### Fixed
 
+### CI/CD
+* Migrated build process from Ant to Maven, including GitHub workflows.
+* Migrated workflow for generating library website from Ant to Maven.
+* Added test coverage via JaCoCo.
+
 
 ## [2.2.0] - 2020-09-18
 

CHANGELOG.md

@@ -1,6 +1,6 @@
 # JavaPermutationTools (JPT): A Java library for computation on permutations and sequences 
 
-Copyright (C) 2018-2020 Vincent A. Cicirello.
+Copyright (C) 2018-2021 Vincent A. Cicirello.
 
 https://www.cicirello.org/
 
@@ -9,7 +9,7 @@ Website: https://jpt.cicirello.org/
 | __Publications About the Library__ | [![DOI](http://joss.theoj.org/papers/10.21105/joss.00950/status.svg)](https://doi.org/10.21105/joss.00950) |
 | :--- | :--- |
 | __Packages and Releases__ | [![Maven Central](https://img.shields.io/maven-central/v/org.cicirello/jpt.svg?label=Maven%20Central)](https://search.maven.org/artifact/org.cicirello/jpt) [![GitHub release (latest by date)](https://img.shields.io/github/v/release/cicirello/JavaPermutationTools?logo=GitHub)](https://github.com/cicirello/JavaPermutationTools/releases) [![DOI](https://zenodo.org/badge/139182095.svg)](https://zenodo.org/badge/latestdoi/139182095) |
-| __Source and Build Info__ | [![build](https://github.com/cicirello/JavaPermutationTools/workflows/build/badge.svg)](https://github.com/cicirello/JavaPermutationTools/actions?query=workflow%3Abuild) [![docs](https://github.com/cicirello/JavaPermutationTools/workflows/docs/badge.svg)](https://github.com/cicirello/JavaPermutationTools/actions?query=workflow%3Adocs) [![GitHub](https://img.shields.io/github/license/cicirello/JavaPermutationTools)](https://github.com/cicirello/JavaPermutationTools/blob/master/LICENSE) |
+| __Source and Build Info__ | [![build](https://github.com/cicirello/JavaPermutationTools/workflows/build/badge.svg)](https://github.com/cicirello/JavaPermutationTools/actions?query=workflow%3Abuild) [![coverage](https://github.com/cicirello/JavaPermutationTools/blob/master/.github/badges/jacoco.svg)](https://github.com/cicirello/JavaPermutationTools/actions?query=workflow%3Abuild) [![docs](https://github.com/cicirello/JavaPermutationTools/workflows/docs/badge.svg)](https://github.com/cicirello/JavaPermutationTools/actions?query=workflow%3Adocs) [![GitHub](https://img.shields.io/github/license/cicirello/JavaPermutationTools)](https://github.com/cicirello/JavaPermutationTools/blob/master/LICENSE) |
 
 ## How to Cite
 
@@ -28,13 +28,9 @@ arrays, and other ordered data types).
 ## Repository Organization
 
 The GitHub repository is organized as follows:
-* The [/build](build) directory contains an ant build file, and other resources related to building the library.
-* The [/dist](dist) directory contains the compiled jar files of the library.
-* The [/docs](docs) directory contains the javadoc documentation in a sub-directory [/docs/api](docs/api). The /docs directory is also the location of the website for the project hosted via GitHub pages at https://jpt.cicirello.org/.
-* The [/examples](examples) directory contains several example programs that use the library, and which demonstrate usage of various features.
-* The [/replication](replication) directory includes source code that recreates results found in publications associated with the library.
-* The [/src](src) directory contains all of the source code.
+* The [/src](src) directory contains all of the source code for JavaPermutationTools.
 * The [/tests](tests) directory contains JUnit test cases for all functionality of the library.
+* The [/docs](docs) directory contains the javadoc documentation in a sub-directory /docs/api. The /docs directory is also the location of the website for the project hosted via GitHub pages at https://jpt.cicirello.org/.
 
 ## Java 8
 
@@ -48,38 +44,30 @@ correspond to incompatible API changes, differences in MINOR correspond
 to introduction of backwards compatible new functionality, and PATCH 
 corresponds to backwards compatible bug fixes. 
 
-## Building the Library (with ant)
+## Building the Library (with Maven)
 
-The /build directory contains an ant build file.  The build file 
-also executes the JUnit tests, and the build directory contains
-the relevant jar files for the JUnit libraries.  If you prefer, 
-you can replace these with the latest versions available
-from https://junit.org/junit4/ (just be sure to edit the property 
-fields in the build.xml to point to the locations of the JUnit jar files).
+The JavaPermutationTools library is built using Maven. The root of the
+repository contains a Maven `pom.xml`.  To build the library, 
+execute `mvn package` at the root of the repository, which
+will compile all classes, run all tests, run javadoc, and generate 
+jar files of the library, the sources, and the javadocs. All build 
+outputs will then be found in the directory `target`.
 
-To execute the build process do one of the following.  If your working 
-directory is the build directory, then simply execute
-`ant` from the command line.  If your working directory is the 
-parent of build, then execute: `ant -f build/build.xml`
+To include generation of a code coverage report during the build,
+execute `mvn package -Pcoverage` at the root of the repository to 
+enable a Maven profile that executes JaCoCo during the test 
+phase. The JaCoCo report will also be found in the target directory.
 
-The default of the provided ant build file, compiles all source 
-files and all JUnit tests, executes all test cases,
-generates the jar file of the library, and compiles the example 
-programs and the experiment replication programs. The 
-build process will terminate on any test case failures.  
+## Example Programs
 
-If you use the ant build file, the build will generate the 
-following directories: bin (for the compiled Java classes),
-testbin (for the compiled JUnit tests), dist (for the jar file of the library), 
-and exbin (for the compiled example
-programs and experiment replication programs).
-
-## Running the Example Programs
-
-The examples directory contains example usage of several of the classes of the API.
-The replication directory additionally contains more complex examples that replicate the
-experiments from published papers that have used the library.  Those directories contain
-READMEs that provide more detail on the examples, including on running the examples.
+There are several example programs available in a separate 
+repository: [cicirello/jpt-examples](https://github.com/cicirello/jpt-examples). The
+examples repository contains example usage of several of the classes of the 
+library. Each of the examples contains detailed comments within the source 
+code explaining the example. Running the examples without reading the source 
+comments is not advised. Some of the example in the examples repository are
+based on the experiments from published papers that have either used the library
+directly, or which led to some of the code in the library.
 
 ## Importing the Library from Maven Central
 
@@ -91,7 +79,7 @@ Central since version 2.1.2).
 <dependency>
   <groupId>org.cicirello</groupId>
   <artifactId>jpt</artifactId>
-  <version>2.1.2</version>
+  <version>2.2.0</version>
 </dependency>
 ```
 
@@ -111,6 +99,12 @@ and (2) add the following to the repositories section of your pom.xml:
 </repository>
 ```
 
+## Downloading Jar Files
+
+If you don't use a dependency manager that supports importing from Maven Central,
+or if you simply prefer to download manually, prebuilt jars are also attached to 
+each [GitHub Release](https://github.com/cicirello/JavaPermutationTools).
+
 ## License
 
 The JPT library is licensed under the [GNU General Public License 3.0](https://www.gnu.org/licenses/gpl-3.0.en.html).