Skip to content

Latest commit

 

History

History
70 lines (37 loc) · 2.46 KB

CONTRIBUTING.md

File metadata and controls

70 lines (37 loc) · 2.46 KB

Contributing Changes to regexes.yaml

Contributing to the project, especially regexes.yaml, is both welcomed and encouraged. To do so just do the following:

  1. Fork the project

  2. Create a branch for your changes

  3. Modify regexes.yaml as appropriate

  4. Create a text-file (e.g. ua.txt) which contains the User-Agent Strings (seperated by newline) you want to add to the testset in ./test_resources/tests.json Please consider only real user-agents catched from your server logs for this file.

  5. Run

     ./js/bin/add.js -u ua.txt -t check.json

    Check the results in check.json

  6. If you are sure that all is ok, run ./js/bin/add.js -u ua.txt

  7. Run all tests with npm test

  8. Push your branch to GitHub and submit a pull request

  9. Monitor the pull request to make sure the Travis build succeeds. If it fails simply make the necessary changes to your branch and push it. Travis will re-test the changes.

That's it. If you don't feel comfortable forking the project or modifying the YAML you can also submit an issue that includes the appropriate user-agent-string and the expected results of parsing.

Thanks!

Advanced

The regexes.yaml does not claim to be perfect. If you encounter that parsing results are too coarse or even wrong you will encounter a lot of test errors while running the tests.

  1. To easily change the test-set contained in ./test_resources/tests.json do the following.

     ./js/bin/regen.js -c

  2. At this stage really check that you did not miss out something.

     diff test_resources/tests.js test_resources/new-tests.json

  3. If you need to rerun tests and do not want to perform the full test-set, the previous tests for the bad-matching tests are stored in ./test_resources/bad-tests.json.

     cp test_resources/bad-tests.json .
 ./js/bin/regen.js -i bad-tests.json -c

    When all is as you expect re-run Step 1. and Step 2.

     ./js/bin/regen.js -c
 diff test_resources/tests.js test_resources/new-tests.json

  4. All is ok now, then replace the test-set

     cp  test_resources/new-tests.js test_resources/tests.json

    And rerun all tests

     npm test

Find the right Regex-Matcher

The tool ./js/bin/debuginfo.js adds for each regex in regexes.yaml a debug information which makes it easier together with regen.js -c to identify the matching regular-expression for a failed test.

Rerunning the tool removes the debuginfo again.