Skip to content

Latest commit

 

History

History
92 lines (71 loc) · 6.03 KB

CONTRIBUTING.md

File metadata and controls

92 lines (71 loc) · 6.03 KB

Contributing to the Secrets Manager API for Java

For general contribution and community guidelines, please see the community repo.

Table of Contents

Prerequisites

Java

To work in this codebase, you will need the latest version of the Java JDK installed.

Docker

This project is container-based and therefore, you will need Docker in order to make and view your changes.

Building and Testing

Before making changes, it is recommended that the test script is run first to ensure that Java and the provided dependencies are not out-of-date. You can run the test script in your shell like so: ./test.sh

NOTE: The tests (for both Conjur OSS and Secrets Manager, Self-Hosted) are part of the build so if a change is made to the actual API, but the tests fail, the build will also fail.

Troubleshooting Steps

This section includes helpful troubleshooting hints to help you navigate the codebase and resolve problems that you might be experiencing during development.

Common Certificate-related Errors

  • org.apache.cxf.interceptor.Fault: Could not send Message
  • sun.security.provider.certpath.SunCertPathBuilderException unable to find valid certification path to requested target

Possible solutions

  1. Check that the $JAVA_HOME path in the container matches the JAVA_PATH variable path in the test script. Otherwise, Java will think a new keystore is being created and will not (by default) look for the certificate in the path given.

  2. Since we are using Java cacerts (Java-specific certificates), check that the fingerprints of the certificate in the test containers match the fingerprints in the appliance.

    To do so:

    1. docker exec into the test container and run keytool -list -keystore $JRE_HOME/lib/security/cacerts -alias <IMPORTED_CERT_ALIAS>. The alias of the certificate can be found in the test script.
      1. If import was successful, the certificate fingerprint (SHA) should be returned.
    2. Navigate to https://localhost:<PORT_OF_CONJUR_CONTAINER> in your browser (make sure the Conjur OSS container is still up and running).
      1. You can find the exact ports by taking a look at each container's exposed ports in the docker-compose.yml file.
      2. You can keep containers up by commenting out the finish function in the test script.
    3. For instructions on how to view certificates in browsers, take a look here.
    4. Check to see if the fingerprints of the host certificate (not the root certificate) match the one that was returned by the keytool.

  3. Create a basic HTTPS client in Java to make the connection to the appliance. If you cannot make the connection (not getting data back), then you know there is a problem with the cacaerts collection (either on import or on creation)

Jenkins Tests Error

  • The input device is not a TTY

TTY ("teletype") is a terminal interface (from when terminals were attached to mainframes) that support input/output streams. Since then, pseudo-terminal drivers/emulators were developed to allow terminals to perform actions and send signals without the need to write to terminal directly. When pushing your changes, you may notice that you are receiving the above error because Jenkins doesn't support terminal connection sessions (with stdin and stdout streams) and therefore doesn't execute its jobs in a TTY. To disable this, add -T to your docker command. NOTE: this can happen with cat as it may sometimes not notice that the input stream has ended.

Releasing

Releases should be created by maintainers only. To create and promote a release, follow the instructions in this section.

Update the changelog and notices

NOTE: If the Changelog and NOTICES.txt are already up-to-date, skip this step and promote the desired build from the main branch.

  1. Create a new branch for the version bump.
  2. Based on the changelog content, determine the new version number and update.
  3. Review the git log and ensure the changelog contains all relevant recent changes with references to GitHub issues or PRs, if possible.
  4. Review the changes since the last tag, and if the dependencies have changed revise the NOTICES to correctly capture the included dependencies and their licenses / copyrights.
  5. Commit these changes - Bump version to x.y.z is an acceptable commit message - and open a PR for review.

Release and Promote

  1. Merging into the main branch will automatically trigger a release. If successful, this release can be promoted at a later time.
  2. Jenkins build parameters can be utilized to promote a successful release or manually trigger aditional releases as needed.
  3. Reference the internal automated release doc for releasing and promoting.

Contribution Workflow

  1. Fork or clone repository
  2. If issue for relevant change has not been created, open one here
  3. Add the implementing label to the issue once you begin to work on it
  4. Create your feature branch (git checkout -b my-new-feature)
  5. Run test script (./test.sh) to ensure tests are not out of date
  6. Once changes are made, run test script again to ensure your changes haven't broken anything
  7. Commit your changes (git commit -m 'Add X feature that does Y')
  8. Push to the branch (git push origin my-new-feature)
  9. Create new Pull Request, linking the issue in the description (e.g. Connected to #123) and ask another developer to review and merge your code
  10. Replace implementing with implemented label in issue