Your contributions to Humanizer are very welcome.
If you find a bug, please raise it as an issue.
Even better fix it and send a pull request.
If you like to help out with existing bugs and feature requests just check out the list of issues and grab and fix one.
Some of the issues are labeled jump in. These issues are generally low hanging fruit so you can start with easier tasks.
This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community. For more information see the .NET Foundation Code of Conduct.
This project uses modern SDK-style .NET projects, so you'll need a current .NET SDK to open and compile the repository.
This project uses GitHub flow for pull requests.
So if you want to contribute, fork the repo, preferably create a local branch, based off of the main branch, to avoid conflicts with other activities, fix an issue, run the repository build and test commands, and send a PR if all is green.
Pull requests are code reviewed. Here is a checklist you should tick through before submitting a pull request:
- Implementation is clean
- Code adheres to the existing coding standards; e.g. no curlies for one-line blocks, no redundant empty lines between methods or code blocks, spaces rather than tabs, etc. There is an
.editorconfigfile that must be respected. - No ReSharper warnings
- There is proper unit test coverage
- If the code is copied from StackOverflow (or a blog or OSS) full disclosure is included. That includes required license files and/or file headers explaining where the code came from with proper attribution
- There are very few or no comments (because comments shouldn't be needed if you write clean code)
- Xml documentation is added/updated for the addition/change
- Your PR is (re)based on top of the latest commits from the
mainbranch (more info below) - Link to the issue(s) you're fixing from your PR description. Use
fixes #<the issue number> - Readme is updated if you change an existing feature or add a new one
- Run the repository test/build commands and ensure there are no test failures
Please rebase your code on top of the latest main branch commits.
Before working on your fork make sure you pull the latest so you work on top of the latest commits to avoid merge conflicts.
Also before sending the pull request please rebase your code as there is a chance there have been new commits pushed after you pulled last.
Please refer to this guide if you're new to git.
One area where Humanizer can always use your help is localisation.
Humanizer ships locale coverage for DateTime.Humanize, TimeSpan.Humanize, ToWords, ToOrdinalWords, ToNumber, numeric ordinalization, date ordinals, clock notation, and compass headings.
Humanizer could definitely do with more translations.
To add a translation for DateTime.Humanize and TimeSpan.Humanize,
fork the repository if you haven't done yet, duplicate one of the YAML locale files under src/Humanizer/Locales, rename it to your target locale code
(for example ru.yml for Russian), translate the locale data, write unit tests for the translation, commit, and send a pull request for it. Thanks.
The YAML schema supports exact phrases, counted forms, aliases, inheritance, and profile data, so most languages can be expressed entirely in locale data without custom runtime code.
If your language still needs formatter-specific behavior beyond the locale schema, subclass DefaultFormatter in a class that represents your language;
e.g. RomanianFormatter and RussianFormatter show the older residual-leaf pattern.
Then return an instance of your class in the Configurator class in the getter of the Formatter property based on the current culture.
Number localization is now authored primarily in YAML under src/Humanizer/Locales. Supported locales should plan ToWords and ToNumber together so the same high-range forms round-trip naturally.
Locale work is not complete unless every canonical surface resolves intentionally, either locale-owned or same-language inherited with proof.
Check out the locale YAML files and the shared number kernels under src/Humanizer/Localisation/NumberToWords and src/Humanizer/Localisation/WordsToNumber for examples of how to express a language in the current pipeline.
If a locale still needs a residual runtime leaf, keep it intentional and document why the shared YAML schema cannot express it yet.
Don't forget to write tests for your localisations. Check out the existing DateHumanizeTests, TimeSpanHumanizeTests, NumberToWordsTests, and locale-specific WordsToNumber tests where the culture supports parsing.