Skip to content

Latest commit

 

History

History
151 lines (107 loc) · 7.07 KB

CONTRIBUTING.md

File metadata and controls

151 lines (107 loc) · 7.07 KB
Raw

Contributing to WireMock

Docs a a Participate

WireMock exists and continues to thrive due to the efforts of over 150 contributors, and we continue to welcome contributions to its evolution. Regardless of your expertise and time you could dedicate, there're opportunities to participate and help the project!

Ways to contribute

This guide is for contributing to WireMock, also known as WireMock Java or WireMock Core. There are many other repositories waiting for contributors, check out the Contributor Guide for the references and details.

Getting started

If you want to contribute to WireMock Java codebase, do the following:

  • Join the community Slack channel, especially the #help-contributing and #wiremock-java channels. The latter is used to coordinate development of this repository.
  • Read the guidelines below
  • Start contributing by creating issues, submitting patches via pull requests, and helping others!

Building WireMock locally

To run all of WireMock's tests:

./gradlew check

To build both JARs (thin and standalone), the JARs will be placed under build/libs.:

./gradlew jar shadowJar

To publish both JARs to your local Maven repository:

./gradlew publishToMavenLocal

If you use IntelliJ, you can also use the corresponding run configurations, Run Tests, Build WireMock and Publish to Maven local respectively.

Contributing Code

Please be mindful of the following guidelines:

  • All changes should include suitable tests, whether to demonstrate the bug or exercise and document the new feature.
  • Please make one change per pull request.
  • If the new feature is significantly large/complex/breaks existing behaviour, please first post a summary of your idea on the GitHub Issue to generate a discussion. This will avoid significant amounts of coding time spent on changes that ultimately get rejected.
  • Try to avoid reformats of files that change the indentation, tabs to spaces etc., as this makes reviewing diffs much more difficult.
  • Abide by the Architecture Rules enforced by ArchUnit.

Before opening a PR

When proposing new features or enhancements, we strongly recommend opening an issue first so that the problem being solved and the implementation design can be discussed. This helps to avoid time being invested in code that is never eventually merged, and also promotes better designs by involving the community more widely.

For straightforward bug fixes where the issue is clear and can be illustrated via a failing unit or acceptance test, please just open a PR.

Code style

WireMock uses the Google Java style guide and this is enforced in the build via the Gradle Spotless plugin.

When running pre-commit checks, if there are any formatting failures the Spotless plugin can fix them for you:

./gradlew spotlessApply

If you use IntelliJ, you can also use the run configuration called Run Spotless, or there's also an IntelliJ plugin for the same purpose.

Testing

WireMock has a fairly comprehensive test suite which ensures it remains robust and correct as the codebase evolves.

In particular, there are acceptance tests for almost all features, where a full WireMock server is started up and tested via its public APIs.

New features should by default come with acceptance tests covering the major positive and negative cases. Unit tests should also be used judiciously where non-trivial logic would benefit from finer-grained checking.

When making performance enhancements a representative benchmark test should be developed using an appropriate tool, and the results before and after applying the change attached to the associated PR.

Writing documentation

It is expected that all new features and enhancements are documented properly, in most cases before the patches are merged.

Most of WireMock's documentation is published on wiremock.org, which is a static website built using Jekyll. The website sources are located here: wiremock/wiremock.org. All the documentation is located under the _docs directory as Markdown files, and it can be edited with all modern text editors and IDEs. See the repository's contributor guide for more information.

Merge process

Merges to this repository can be performed by the WireMock maintainer (Tom Akehurst) and by co-maintainers assigned by him. This is a community role designed for WireMock itself and other key repositories, specifically to improve velocity of reviews and changes.

  • The maintainers are responsible to verify the pull request readiness in accordance with contributing guidelines (e.g. code quality, test automation, documentation, etc.). The pull request can only be approved if these requirements are met
  • In the beginning, a review by one co-maintainer is required for the merge, unless there are negative reviews and unaddressed comments by other contributors
  • After the approval, it is generally recommended to give at least 24 hours for reviews before merging

What can be merged by co-maintainers

For WireMock 3.x and beyond, co-maintainers can merge the following pull requests:

  • Minor features and improvements that do not impact the WireMock architecture
  • Refactorings, including the major ones, e.g. Guava replacement
  • Test Automation
  • Non-production repository changes: documentation (including Javadoc), GitHub Actions, bots and automation
  • Dependency updates for shaded dependencies, patch/minor versions for projects following the Semantic Versioning notation

For the WireMock 2.x branch, a decision of BDFL is is needed for any patch.

What CANNOT be merged by co-maintainers without BDFL’s approval

The following changes need a review by Tom Akehurst before being merged.

  • Any compatibility breaking changes, including binary API and REST API, unless pre-approved by the BDFL in the associated GitHub issue
  • New request matchers (patterns)
  • Substantial changes to WireMock Architecture and API. Examples: New REST API end-points, major features like GraphQL fetching
  • Inclusion of new libraries, even if shaded
  • Major version Dependency updates, e.g. Jetty 11 => 12
  • Changes in the deliverable artefacts, e.g. new modules