Skip to content

Latest commit

 

History

History
189 lines (135 loc) · 5.76 KB

CONTRIBUTING.md

File metadata and controls

189 lines (135 loc) · 5.76 KB
Raw

How to contribute to gnparser project

Did you find a bug?

  • Ensure the bug was not already reported by searching on GitHub under Issues.

  • If you're unable to find an open issue addressing the problem, open a new one. Be sure to include a title and clear description, as much relevant information as possible, and a code sample or an executable test case via https:parser.globalnames.org demonstrating the expected behavior that is not occurring.

  • Make sure you do not put more than one bug report in the new issue.

Do you intend to add a new feature or change an existing one?

Did you write a patch that fixes a bug?

  • Open a new GitHub pull request with the patch.

  • Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable.

  • Clearly state if your PR is a proof of concept and what needs to be done to finish it, or, if it is ready to merge patch with tests and documentation added.

Did you write a client for your favorite language to access gnparser functionality via REST api?

Let us know about your client on GlobalNames gitter group.

Do you have questions about the source code?

Would you like to contribute, but do not know how?

  • Read the next section about configuring environment for the project.

Setting up gnparser programming environment

Install Go

Download and install Go for your operating system. Make sure you configured GOPATH environment library.

You need Go v1.16.x or higher.

Install gnparser code

Before Go v1.11 all Go code had to be organized inside of the GOPATH directory. Now, for projects like gnparser that use Go modules it is not necessary, however many tools still behave assuming old ways, so we recommend to setup gnparser code traditional way.

mkdir -p $GOPATH/src/github.com/gnames
cd $GOPATH/src/github.com/gnames
git clone https://github.com/gnames/gnparser.git
# or use URL of your fork on GitHub or GitLab

cd gnparser

gnparser uses several external tools and technologies:

  1. Parsing Expression Grammar tool to generate parsing code.

  2. Cobra CLI framework for creating command line application.

  3. goimport tool for fixing imports in PEG autogenerated go code.

To install them run

make tools

To create a gnparser executable and place it to $GOPATH/bin

make

Now you should be able to use gnparser compiled from the code:

gnparser -f pretty "Pica pica (Linnaeus, 1758)"

To run tests

make test

or

go test ./...

To generate tests automatically

If your change generates a lot of changes in testdata/test_data.md and/or testdata/test_data_cultivars.md you can generate testdata/test_data_new.md and testdata/test_data_cultivars_new.md files using gentest.go tool.

cd tools
go run gentest.go
cd ../testdata
ls

You will have two new files in testdata. It is VERY important now to check difference between old and new test files before making the next step:

mv test_data_new.md test_data.md
mv test_data_cultivars_new.md test_data_cultivars.md

Benchmarks

Benchmarks are located in gnparser_test.go

To run benchmarks from the project's root:

# this command will install benchstat
make tools

go test -bench=. -benchmem -count=10 -run=XXX > bench.txt && benchstat bench.txt

After running you should get results similar to:

name                                     time/op
Parse/Parse_to_object_once-16            73.0µs ± 1%
Parse/Parse_to_object_once_with_Init-16  83.2µs ± 1%
Parse/Parse_to_object-16                 67.5ms ± 1%
Parse/Parse_to_JSON-16                   71.5ms ± 1%
Parse/Parse_to_JSON_(Details)-16         71.8ms ± 1%
Parse/Parse_to_CSV-16                    69.1ms ± 1%

name                                     alloc/op
Parse/Parse_to_object_once-16            10.9kB ± 0%
Parse/Parse_to_object_once_with_Init-16  23.8kB ± 0%
Parse/Parse_to_object-16                 15.5MB ± 0%
Parse/Parse_to_JSON-16                   17.2MB ± 0%
Parse/Parse_to_JSON_(Details)-16         17.2MB ± 0%
Parse/Parse_to_CSV-16                    16.2MB ± 0%

name                                     allocs/op
Parse/Parse_to_object_once-16               250 ± 0%
Parse/Parse_to_object_once_with_Init-16     409 ± 0%
Parse/Parse_to_object-16                   235k ± 0%
Parse/Parse_to_JSON-16                     242k ± 0%
Parse/Parse_to_JSON_(Details)-16           242k ± 0%
Parse/Parse_to_CSV-16                      240k ± 0%

Accessing a raw parsed AST tree

PEG parser generates it own abstract syntax tree (AST), that later gets conberted into a gnparser specific AST. Sometimes it is useful to see the raw tree of nodes. To do that, open gnparser/gnparser/cmd/root.go, change const debug to true and run make. After that you will be able to examing raw tree of a string, for example:

gnparser "Bubo bubo"