CONTRIBUTING.md

Contributing to trurl

This document is intended to provide a framework for contributing to trurl. This document will go over requesting new features, fixing existing bugs and effectively using the internal tooling to help PRs merge quickly.

Opening an issue

trurl uses GitHubs issue tracking to track upcoming work. If you have a feature you want to add or find a bug simply open an issue in the issues tab. Briefly describe the feature you are requesting and why you think it may be valuable for trurl. If you are reporting a bug be prepared for questions as we will want to reproduce it locally. In general providing the output of trurl --version along with the operating system / Distro you are running is a good starting point.

Writing a good PR

trurl is a relatively straightforward code base, so it is best to keep your PRs straightforward as well. Avoid trying to fix many bugs in one PR, and instead use many smaller PRs as this avoids potential conflicts when merging. trurl is written in C and uses the curl code style. PRs that do not follow to code style will not be merged in.

trurl is in its early stages, so it's important to open a PR against a recent version of the source code, as a lot can change over a few days. Preferably you would open a PR against the most recent commit in master.

If you are implementing a new feature, it must be submitted with tests and documentation. The process for writing tests is explained below in the tooling section. Documentation exists in two locations, the man page (trurl.1) and the help prompt when running trurl -h. Most documentation changes will go in the man page, but if you add a new command line argument then it must be documented in the help page.

It is also important to be prepared for feedback on your PR and adjust it promptly.

Tooling

The trurl repository has a few small helper tools to make development easier.

checksrc.pl is used to ensure the code style is correct. It accepts C files as command line arguments, and returns nothing if the code style is valid. If the code style is incorrect, checksrc.pl will provide the line the error is on and a brief description of what is wrong. You may run make checksrc to scan the entire repository for style compliance.

test.py is used to run automated tests for trurl. It loads in tests from test.json (described below) and reports the number of tests passed. You may specify the tests to run by passing a list of comma-separated numbers as command line arguments, such as 4,8,15,16,23,42 Note there is no space between the numbers. test.py may also use valgrind to test for memory errors by passing --with-valgrind as a command line argument, it should be noted that this may take a while to run all the tests. test.py will also skip tests that require a specific curl runtime or buildtime.

Adding tests

Tests are located in tests.json. This file is an array of json objects when outline an input and what the expected output should be. Below is a simple example of a single test:

    {
        "input": {
            "arguments": [
                "https://example.com"
            ]
        },
        "expected": {
            "stdout": "https://example.com/\n",
            "stderr": "",
            "returncode": 0
        }
    }

"arguments" is an array of the arguments to run in the test, so if you wanted to pass multiple arguments it would look something like:

   {
      "input": {
          "arguments": [
              "https://curl.se:22/",
              "-s",
              "port=443",
              "--get",
              "{url}"
          ]
      },
      "expected": {
          "stdout": "https://curl.se/\n",
          "stderr": "",
          "returncode": 0
      }
  }

trurl may also return json. It you are adding a test that returns json to stdout, write the json directly instead of a string in the examples above. Below is an example of what stdout should be if it is a json test, where "input" is what trurl accepts from the command line and "expected" is what trurl should return.

"expected": {
    "stdout": [
        {
          "url": "https://curl.se/",
          "scheme": "https",
          "host": "curl.se",
          "port": "443",
          "raw_port": "",
          "path": "/",
          "query": "",
          "params": []
        }
    ],
    "returncode": 0,
    "stderr": ""
}

Tips to make opening a PR easier

• Run make checksrc and make test-memory locally before opening a PR. These ran automatically when a PR is opened so you might as well make sure they pass before-hand.
• Update the man page and the help prompt accordingly. Documentation is annoying but if everyone writes a little it's not bad.
• Add tests to cover new features or the bug you fixed.