From bfaa8a8a5acb45aa3a2baafaf0e9f6b7b3c31749 Mon Sep 17 00:00:00 2001 From: Mark Waite Date: Sat, 14 Dec 2024 15:15:16 -0700 Subject: [PATCH] Move contribution guidelines into CONTRIBUTING page (#112) * Move contribution guidelines into CONTRIBUTING page Minor improvements to phrasing in the plugin documentation. Include instructions for developers that want to use the plugin, modeled after the HTTP client API 4 instructions. * Remove unmaintained GitPod references --- .gitpod.Dockerfile | 8 ------- .gitpod.yml | 16 ------------- CONTRIBUTING.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++ README.md | 55 ++++++++++++++++++++++-------------------- 4 files changed, 88 insertions(+), 50 deletions(-) delete mode 100644 .gitpod.Dockerfile delete mode 100644 .gitpod.yml create mode 100644 CONTRIBUTING.md diff --git a/.gitpod.Dockerfile b/.gitpod.Dockerfile deleted file mode 100644 index b4e74a9..0000000 --- a/.gitpod.Dockerfile +++ /dev/null @@ -1,8 +0,0 @@ -FROM gitpod/workspace-full - -USER gitpod - -RUN bash -c ". /home/gitpod/.sdkman/bin/sdkman-init.sh && \ - sdk install java 17.0.3-tem && \ - sdk install java 11.0.15-tem && \ - sdk default java 17.0.3-tem" diff --git a/.gitpod.yml b/.gitpod.yml deleted file mode 100644 index 9675fb7..0000000 --- a/.gitpod.yml +++ /dev/null @@ -1,16 +0,0 @@ -# Using an updated Gitpod docker image (when using a non default JDK or tools) -image: - file: .gitpod.Dockerfile - -tasks: - - init: sdk default java 11.0.15-tem && mvn clean verify - -vscode: - extensions: - - bierner.markdown-preview-github-styles - - vscjava.vscode-java-pack - - redhat.java - - vscjava.vscode-java-debug - - vscjava.vscode-java-dependency - - vscjava.vscode-java-test - - vscjava.vscode-maven diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ff7c6d3 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,59 @@ +# Contributing to the plugin + +Plugin source code is hosted on [GitHub](https://github.com/jenkinsci/docker-java-api-plugin). +New feature proposals and bug fix proposals should be submitted as +[GitHub pull requests](https://help.github.com/articles/creating-a-pull-request). +Your pull request will be evaluated by the [Jenkins job](https://ci.jenkins.io/job/Plugins/job/docker-java-api-plugin/). + +Before submitting your change, please assure that you've added tests which verify your change. + +## Code formatting with spotless + +Source code and pom file formatting are maintained by the `spotless` maven plugin. +Before submitting a pull request, please format with: + +* `mvn spotless:apply` + +## Static analysis with spotbugs + +Please don't introduce new spotbugs output. + +* `mvn spotbugs:check` to analyze project using [Spotbugs](https://spotbugs.github.io) +* `mvn spotbugs:gui` to review report using GUI + +## Code Coverage + +[JaCoCo code coverage](https://www.jacoco.org/jacoco/) reporting is available as a maven target and is [reported](https://ci.jenkins.io/job/Plugins/job/docker-java-api-plugin/) by the [Jenkins warnings plugin](https://plugins.jenkins.io/warnings-ng/). +Please try to improve code coverage with tests when you submit a pull request. + +* `mvn -P enable-jacoco clean install jacoco:report` to report code coverage with JaCoCo. + +### Reviewing Code Coverage + +The code coverage report is a set of HTML files that show methods and lines executed. +The following commands will open the `index.html` file in the browser. + +* Windows - `start target\site\jacoco\index.html` +* Linux - `xdg-open target/site/jacoco/index.html` + +The file will have a list of package names. +Click on them to find a list of class names. + +The lines of the code will be covered in three different colors, red, green, and orange. +Red lines are not covered in the tests. +Green lines are covered with tests. + +## Maintaining automated tests + +Automated tests are run as part of the `verify` phase. +Run automated tests in a development environment with the command: + +``` +$ mvn clean verify +``` + +## Report an Issue + +Use the ["Report an issue" page](https://www.jenkins.io/participate/report-issue/redirect/#23136) to submit bug reports. +Please review [existing issues](https://issues.jenkins.io/issues/?jql=resolution%20is%20EMPTY%20and%20component%3D23136) before submitting a new issue. +Please use the ["How to Report an Issue"](https://www.jenkins.io/participate/report-issue/) guidelines when reporting issues. diff --git a/README.md b/README.md index e54619e..e447966 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,35 @@ # Docker Java API Plugin -This plugin exposes the [docker-java](http://github.com/docker-java/docker-java) API to Jenkins plugins. +This plugin provides the [docker-java](http://github.com/docker-java/docker-java) API to Jenkins plugins. Plugins using docker-java should depend on this plugin and not directly on docker-java. Only the Apache HttpClient 5 transport is available; the Jersey transport does not work. -# Environment - -The following build environment is required to build this plugin - -* Java 11 and Maven 3.8.1 - -# Build - -To build the plugin locally: - - mvn clean verify - -# Release - -To release the plugin: - - mvn release:prepare release:perform -B - -# Test local instance - -To test in a local Jenkins instance - - mvn hpi:run - - [wiki]: http://wiki.jenkins-ci.org/display/JENKINS/Docker+Java+API+Plugin +## Using the API in your plugin + +Replace the dependency to `com.github.docker-java:docker-java` with a dependency to `org.jenkins-ci.plugins:docker-java-api`. +Avoid version conflicts by using the [Jenkins plugin BOM](https://github.com/jenkinsci/bom#readme) rather than depending on a specific version. + +* Before: + ``` + + ... + + com.github.docker-java + docker-java + 3.4.1 + + ... + + ``` +* After: + ``` + + ... + + org.jenkins-ci.plugins + docker-java-api + + ... + + ```