From fcf6d841ae97e724274986c062525eea6386b6cb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?D=C5=BEuris?= Date: Tue, 19 Mar 2024 00:09:02 +0200 Subject: [PATCH] Expand contibuting notes --- CONTRIBUTING.md | 83 +++++++++++++++-------------- README.md | 135 ++++++++++++++++++++++++++---------------------- 2 files changed, 116 insertions(+), 102 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 74c61ed..11934ff 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,39 +1,44 @@ -## Project - -All calculators must implement `Support\CalculatorInterface`. - -Aim for 100% line coverage in tests. If you can't reach a line in a test, why -have the line at all? - -## Testing - -We use composer to set up phpunit and autoloading. - -``` -composer install -``` - -The test script is also defined in composer. - -``` -composer test -``` - -The test script includes code coverage report which relies on xdebug. If you -don't have xdebug, you can run the tests directly. - -``` -vendor/bin/phpunit -``` - -## TODO - -Any improvements will be seriously considered for merging into the package. - -Well thought out improvements to documentation would be greatly appreciated. - -Additional editions for any of the calculators will be accepted as long as -those are actual scoring systems used somewhere. - -Regarding inclusion of additional calculators — we will have to weight -relevance against the burden of maintenance. +## Project + +All calculators must implement `Support\CalculatorInterface`. + +Aim for 100% line coverage in tests. If you can't reach a line in a test, why +have the line at all? + +## Testing + +We use composer to set up phpunit and autoloading. + +``` +composer install +``` + +The test script is also defined in composer. + +``` +composer test +``` + +The test script includes code coverage report which relies on xdebug. If you +don't have xdebug, you can run the tests directly. + +``` +vendor/bin/phpunit +``` + +## Adding/editing data + +The contents in `data/` is generated from `resources/` via scripts in `bin/`. +Only edit `resources/`, not data. + +## TODO + +Any improvements will be seriously considered for merging into the package. + +Well thought out improvements to documentation would be greatly appreciated. + +Additional editions for any of the calculators will be accepted as long as +those are actual scoring systems used somewhere. + +Regarding inclusion of additional calculators — we will have to weight +relevance against the burden of maintenance. diff --git a/README.md b/README.md index 4e58ff6..2e48b94 100644 --- a/README.md +++ b/README.md @@ -1,63 +1,72 @@ -# IaafPoints - -PHP library to calculate World Athletics (IAAF) scoring points of athletics and -WA (IAAF) scoring points for combined events. And some other evaluations of -track and field results. - -> IAAF is rolling a rebrand to WA, but we currently have no plans to rename the -> package or any of classes. - -The WA scoring tables that we reproduce are these ones: -https://www.worldathletics.org/about-iaaf/documents/technical-information#collapsescoring-tables - -This package is used for the stats system of [Latvian Athletics Association](https://athletics.lv). - -## Table of Contents - -- [Installation](#installation) -- [Usage](#usage) -- [Changelog](#changelog) -- [License](#license) - -## Installation - -Use composer: - -```sh -composer require glaivepro/iaafpoints -``` - -## Usage - -This package provides mutliple calculators that all provide the same interface. - -```php -// Calculator and use-case specific options. -$options = [ - 'gender' => 'm', - 'venueType' => 'outdoor', - 'discipline' => '200m', -]; - -// Create a calculator instance -$calculator = new \GlaivePro\IaafPoints\IaafCalculator($options); - -// Evaluate a result getting some points or a class assigned to result. -$points = $calculator->evaluate(21.61); -// 980 - -// Update options -$calculator->setOptions(['gender' => 'f']); -$points = $calculator->evaluate(21.61); -// 1279 -``` - -See [docs](docs) for more details. - -## Changelog - -It's [here](CHANGELOG.md). - -## License - -This package is licensed under the [MIT license](LICENSE.md). +# IaafPoints + +PHP library to calculate World Athletics (IAAF) scoring points of athletics and +WA (IAAF) scoring points for combined events. And some other evaluations of +track and field results. + +> IAAF is rolling a rebrand to WA, but we currently have no plans to rename the +> package or any of classes. + +The WA scoring tables that we reproduce are these ones: +https://www.worldathletics.org/about-iaaf/documents/technical-information#collapsescoring-tables + +This package is used for the stats system of [Latvian Athletics Association](https://athletics.lv). + +## Table of Contents + +- [Installation](#installation) +- [Usage](#usage) +- [Contributing](#contributing) +- [Changelog](#changelog) +- [License](#license) + +## Installation + +Use composer: + +```sh +composer require glaivepro/iaafpoints +``` + +## Usage + +This package provides mutliple calculators that all provide the same interface. + +```php +// Calculator and use-case specific options. +$options = [ + 'gender' => 'm', + 'venueType' => 'outdoor', + 'discipline' => '200m', +]; + +// Create a calculator instance +$calculator = new \GlaivePro\IaafPoints\IaafCalculator($options); + +// Evaluate a result getting some points or a class assigned to result. +$points = $calculator->evaluate(21.61); +// 980 + +// Update options +$calculator->setOptions(['gender' => 'f']); +$points = $calculator->evaluate(21.61); +// 1279 +``` + +See [docs](docs) for more details. + +## Contributing + +> [!IMPORTANT] +> Do not edit anything in `data/`, edit it in `resources/`. The files in `data/` +> are auto-generated from files in `resources/`. + +More [here](CONTRIBUTING.md). + +## Changelog + +It's [here](CHANGELOG.md). + +## License + +This package is licensed under the [MIT license](LICENSE.md).