Skip to content

Latest commit

 

History

History
196 lines (138 loc) · 6.39 KB

CONTRIBUTING.md

File metadata and controls

196 lines (138 loc) · 6.39 KB

Contributing to the WireMock website

a

All contributions to the website are welcome! Whether you develop new documentation, want to share your use-case, fix an issue or improve the website's look and feel... just submit a pull request! See the contributor notes below.

General WireMock contributing guide is available here.

Discussing changes

Make sure to join the community Slack as documented in the contributing guide. After that, all changes can be discussed in the #help-contributing or #documentation channels. Do not hesitate to ask there if you hit an obstacle.

Key locations

WireMock 3 docs

WireMock Java 3.x documentation, including API specifications and other resources is located in the main branch.

WireMock 2.x docs archive

WireMock Java 2.x documentation (wiremock.org/2.x) documentation archive, including API specifications and other resources is located in the 2.x branch that is included as a submodule and build by the CD flow. To update the documentation, submit pull requests against the branch, and they will be included into the main release line.

Documentation

The documentation is built using MkDocs, mkdocs-multirepo-plugin and Material for MkDocs

Building

The documentation website uses some sources from submodules, so make sure to pull them before building the site.

Requirements:

  • Python and PiP, recent versions
  • Submodules are pulled in your local git clone
pip install -r requirements.txt
mkdocs build

Local development

To serve the site locally:

mkdocs serve

WARNING: Note that the multi-repo site maybe quite slow during the first build and then during the rebuilds. You can disable it for local development just by commenting out the plugin section in mkdocs.yml The same goes to the SCSS compiler which cannot be disabled. There are jdoiro3/mkdocs-multirepo-plugin #129 and orzih/mkdocs-extra-sass-plugin #6 submitted to improve the developer experience.

Code Tabs

To reduce vertical space and provide examples by multiple technology stacks, we added support for code tabs in the documentation. See the example here: https://wiremock.org/docs/stubbing/ .

Example:

    
=== "JSON"
    
    ```json
    {
      "request": {
        "method": "GET",
        "url": "/some/thing"
      }
      "response": {
        "status": 200,
        "body": "Hello, world!",
        "headers": {
            "Content-Type": "text/plain"
        }
      }
    }
    ```
    
    
=== "Java"
    
    ```java
    @Test
    public void exactUrlOnly() {
        stubFor(get(urlEqualTo("/some/thing"))
                .willReturn(aResponse()
                    .withHeader("Content-Type", "text/plain").withBody("Hello world!")));
    }
    ```

When editing the existing code, make sure to also copy-edit text around it to ensure consistency.

Main site

Preparing the developer environment

The website is powered by Jekyll, and hence the Ruby developer environment is needed. It is recommended to use Ruby 2.7.6 because of the known compatibility issues between recent Jekyll version and Ruby 3. The website can be developed on both Windows and Unix systems, as long as the environment is set properly.

Prerequisites:

  • Ruby 2.7.6
  • Bundler 2.4.10

Building the website

# Install the dependencies including Jekyll
bundle install

## Build the website
bundle exec jekyll build --config '_config.yml'

Note that `_config_preview.yml' is used to disable analytics in the deployed versions

Running the website locally

You can run the website locally and get live preview of the changes on the website and in the documentation contents. To do so, run the following command:

bundle exec jekyll serve --config '_config.yml'

It will start the website on http://localhost:4000.

Preview and Previous site baselines

The website may include preview and deprecated baselines, mainly to serve the documentation. The websites have slightly different layouts to help users navigate (links, headers, etc.).

Alternative baselines are managed in the main branch, but the content comes from other Git branches. For example, if the 4.x baseline is a preview one...

  • There is a branch in the repository, for example 4.x for WireMock 4
  • There is a wiremorg.org/4.x entry on the website. It is included from the branch via Git submodules and packaging scripts in GitHub Actions
  • For this version, there is a _config-4.x.yml file that defines configuration overrides for this version
  • To build and test the baseline on a local machine, one needs to include the overrides config file into jekyll build and jekyll serve commands. For example, bundle exec jekyll serve --config '_config.yml,_config-4.x.yml'.

Checking for broken links

The CI will soon verify that, but for now you can check manually, e.g. with the broken-link-checker.

blc http://localhost:4000/ --exclude-external

A/B Testing

Occasionally we run A/B tests to find out what design changes might help our users navigate the site.

Major changes to navigation and layout can impact the results of A/B tests, so we will be delaying merges of non-critical pull requests that impact pages and components under test. You can find the list of ongoing A/B tests and contacts (as assignees) using this GitHub Issue query

Deploying the website

The repository includes the GitHub action that automatically deploys the website upon merge to the main branch. Once your pull requests is reviewed and merged by the maintainers, it will be automatically deployed to wiremock.org.

For manual deployments, there are legacy script in .scripts. Most likely you do not need them, unless something went horribly wrong.