Contributing
Last updated
Was this helpful?
Last updated
Was this helpful?
Thanks for contributing to ObjectMappers!
This is a set of guidelines for contributing to IceCore Hashids. Please take a moment to review this document to make the contribution process easy and effective for everyone involved.
Following these guidelines helps to communicate that you respect the time of the developers managing and developing this open source project. In return, they should reciprocate that respect in addressing your issue, assessing changes, and helping you finalize your pull requests.
As for everything else in the project, the contributions to IceCore Hashids are governed by our . By participating, you are expected to uphold this code. Please report unacceptable behavior via .
ObjectMappers is an open source project and we love to receive contributions from the community! There are many ways to contribute, from , , which can be incorporated into IceCore Hashids itself by .
The project development workflow and process uses - and management to track issues and pull requests.
Before you continue with this contribution guideslines we highly recommend to read the awesome GitHub on how to .
A bug is a demonstrable problem that is caused by the code in the repository. This section guides you through submitting a bug report for IceCore Hashids. Following these guidelines helps maintainers and the community understand your report, reproduce the behavior and find related reports.
Do NOT report security vulnerabilities in public issues! Please contact the core team members and the project owner in a responsible manner by only. We will assess the issue as soon as possible on a best-effort basis and will give you an estimate for when we have a fix and release available for an eventual public disclosure.
Use the — check if the issue has already been reported. If it has and the issue is still open, add a comment to the existing issue instead of opening a new one. If you find a closed issue that seems like it is the same thing that you are experiencing, open a new issue and include a link to the original issue in the body of your new one.
Check if the issue has been fixed — try to reproduce it using the and branch in the repository.
Isolate the problem — ideally create a .
When you are creating a bug report, please provide as much detail and context as possible. Fill out , the information it asks for helps maintainers to reproduce the problem and resolve issues faster.
Use a clear and descriptive title for the issue to identify the problem.
Describe the exact steps which reproduce the problem in as many details as possible.
Include screenshots and animated GIFs which show you following the described steps and clearly demonstrate the problem.
Provide specific examples to demonstrate the steps. Include links to files or GitHub projects, or copy/pasteable snippets. If you are providing snippets in the issue, use or .
If possible please provide more context by answering these questions:
Did the problem start happening recently (for example after updating to a new version of IceCore Hashids) or was this always a problem? If the problem started happening recently, can you reproduce the problem in an older version of IceCore Hashids? What is the most recent version in which the problem does not happen?
Can you reliably reproduce the issue? If not, provide details about how often the problem happens and under which conditions it normally happens.
Please include details about your configuration and environment:
What is the version of IceCore Hashids you are using?
What is the name and the version of the OS you're using?
Have you tried to reproduce it on different OS environments and if yes is the behavior the same for all?
Which Java JDK/JRE distribution and version are you using? (Oracle, OpenJDK, ...)
Are you running the project with your IDE or Maven?
Are you using any additional CLI arguments for Java or Maven?
What is the name and the version of the IDE you're using?
This section guides you through submitting an enhancement suggestion, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion and find related suggestions.
Use a clear and descriptive title for the issue to identify the suggestion.
Provide a step-by-step description of the suggested enhancement in as many details as possible and provide use-cases.
Describe the current behavior and explain which behavior you expected to see instead and why.
Explain why this enhancement would be useful to most IceCore Hashids users.
List some other libraries where this enhancement exists.
This section guides you through submitting an pull request. Following these guidelines helps maintainers and the community to better understand your code.
Use a clear and descriptive title for the pull request
Include screenshots and animated GIFs which show you following the described steps and clearly demonstrate the change.
Remain focused in scope and avoid to include unrelated commits.
Features and improvements should always be accompanied with tests and documentation. If the pull request improves the performance consider to include a benchmark test, optimally including a chart.
Lint and test before submitting the pull request.
IceCore Hashids has two main sets of documentation: the docs and guides, which helps users to learn about the project, and the API, which serves as a reference.
master - The source code of HEAD always reflects a tagged release version.
develop - The default branch where the source code of HEAD always reflects a state with the latest development state.
Some issues are created with missing information, not reproducible, or plain invalid. You can help to make it easier for maintainer to understand and resolve them faster. since handling issues takes a lot of time that could rather spend on writing code.
We're always looking for more opinions on discussions in issues and pull request reviews which is a good opportunity to influence the future direction of IceCore Hashids.
Every major open source project has its own style guide, a set of standards and conventions for the writing and design of code, documentations and Git commit messages. It is much easier to understand a large codebase when all the code in it is in a consistent style.
A style guide establishes and enforces style to improve the intelligibility and communication within the project community. It ensures consistency and enforces best practice in usage and language composition.
IceCore Hasids adheres to the [Nullables Studio Java Style Guide][styleguide-java-github].
[![][styleguide-java-badge]][styleguide-java-github]
A well-crafted Git commit message is the best way to communicate context about a change to the maintainers. The code will tell what changed, but only the commit message can properly tell why. Re-establishing the context of a piece of code is wasteful. We can't avoid it completely, so our efforts should go to reducing it as much as possible.
IceCore Hasids adheres to the [Nullables Studio Git Style Guide][styleguide-git-github].
[![][styleguide-git-badge]][styleguide-git-github]
A Minimal, Complete, and Verifiable Example.
…Minimal – Use as little code as possible that still produces the same behavior
…Complete – Provide all parts needed to reproduce the behavior
…Verifiable – Test the code you're about to provide to make sure it reproduces the behavior
The more code there is to go through, the less likely developers can understand your enhancement or find the bug. Streamline your example in one of two ways:
Restart from scratch. Create new code, adding in only what is needed to demonstrate the behavior and is also useful if you can't post the original code publicly for legal or ethical reasons.
Divide and conquer. When you have a small amount of code, but the source of the bug is entirely unclear, start removing code a bit at a time until the problem disappears – then add the last part back and document this behavior to help developers to trace- and debug faster.
Make sure all resources and code necessary to reproduce the behavior is included. The problem might not be in the part you suspect it is, but another part entirely.
To entirely understand your enhancement or bug report, developers will need to verify that it exists:
Follow the contribution guidelines regarding the description and details. Without information developers won't be able to understand and reproduce the behavior.
Eliminate any issues that aren't relevant. Ensure that there are no compile-time errors.
Make sure that the example actually reproduces the problem. Sometimes the bug gets fixed inadvertently or unconsciously while composing the example or does not occur when running on fresh machine environment.
Use the — check if this enhancement has already been suggested. If it has and the issue is still open, add your additions as comment to the existing issue instead of opening a new one.
Check if the enhancement has already been implemented — use the and branch to ensure that the feature or improvement has not already been added.
Provide a reduced show case — ideally create a .
Before creating enhancement suggestions, please check if your idea fits with the scope and provide as much detail and context as possible using a structured layout like the .
Provide examples to demonstrate the need of an enhancement. Include copy/pasteable snippets which you use in those examples, use or .
Please or first before embarking on any significant pull request (for example implementing features, refactoring code, fixing a bug), otherwise you risk spending a lot of time working on something that the core team members and project owner might not want to merge into the project.
When you are submitting an pull request, please provide as much detail and context as possible. Fill out to help maintainers to understand your submitted code.
Do not include issue numbers in the pull request title but fill in the metadata section at the top of the making use of the to link to specific or .
Make sure to follow the and style guides.
Make sure to create the pull request from a .
All pull requests must be send against the develop branch - Please read the section below for details about the branching model.
You can help improve the docs and guides by making them more coherent, consistent or readable, adding missing information, correcting factual errors, fixing typos, bringing them up to date when there are differences to the latest version. This can be done by submitting a and then opening a for it.
The IceCore Hashids uses the branching model. The repository consists of two core branches with an infinite development lifecycle:
All for the limited development lifecycle story**/**topic branches must be send against the develop branch.
The issue label is a good place to find ongoing discussions and questions.
The style guide assumes that you are familiar with the branching model.
When , sometimes even when , the issue can be processed faster if you provide code for reproduction. That code should be…
A MCVE is a common practice like on and sometimes it is also called , a Short, Self Contained, Correct (Compilable), Example.
The recommended way for GitHub based projects is to create it as or new repository, but of course you can , use any free code paste- or file hosting service or paste the code in into the issue.
Minimal does not mean terse – don't sacrifice communication to brevity. Use consistent naming and indentation following the , and include comments if needed to explain portions of the code.
IceCore Hashids follows the [Arctic Versioning Specification][arcver] (ArcVer) which is a lightweight and fully compatible derivative of (SemVer). We release patch versions for bugfixes, minor versions for enhancements like new features and improvements, and major versions for any backwards incompatible changes. Deprecation warnings are introduced for breaking changes in a minor version so that users learn about the upcoming changes and migrate their code in advance.
Every significant change is documented in the .
Thanks for the inspirations and attributions to GitHub's and various contribution guides of large open source projects like , and .