Thank you for considering a contribution to LicenseScout!
We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great.
This guide explains how to:
- maximize the chance of your changes being accepted
- work on the this project's code base
- get help if you encounter trouble
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
You will need to complete a Contribution License Agreement (CLA) before any pull request can be accepted. When you submit a Pull Request, a CLA assistant bot will confirm you have completed the agreement, or provide you with an opportunitiy to do so.
Before starting to work on a feature or a fix, please open an Issue (proposal) to discuss the use case or bug with us. This can save both you and us a lot of time. For any non-trivial change, we'll ask you to create a short design document explaining:
- Why is this change done? What's the use case?
- How is the functional design?
- How should the technical design look like?
- Are there any dependencies to other parts?
- What test cases should it have? What could go wrong?
- How will it roughly be implemented? (We'll happily provide code pointers to save you time)
This can be done directly inside the GitHub Issue and/or if accepted - later in the Pull Request.
Please create a new Issue in github using the provided template, and make sure to attach labels. Mark the issue as one of the following:
- Bug Reports
- Proposal (feature request / improvements / etc.)
To propose a change or new feature, review the Do's and Dont's below and then open an issue using this template.
- Do open one Issue for one issue.
- Do open two Issues for two issues.
- Do not tack on “Oh by the way here’s another problem I noticed” to an unrelated Issue.
- Do keep facts and opinions separate, ideally facts first and opinions at the end.
- Do spend extra time writing a good title.
- Do be specific, especially in reproduction steps.
- Do answer other people’s questions if you know the answer. Responding to questions is not a privilege reserved for just maintainers.
- Do not guess if you do not know the answer to someone’s question.
- Do be specific in describing what you want to be added and how it would solve a problem you are facing.
- Do not open an Issue with just “make X better” or “improve X”.
- Do open an Issue for a feature request with “Make X better by adding Y because Z”.
- Do not confuse feature size with project fit. Fit is determined first, then implementation. Some fitting features will take a long time to implement because they are large. But no unfit features should be implemented no matter how easy.
- Do close feature requests you no longer need. If someone else has the same request, they can open a separate issue more focused on their needs.
Open proposals are still under discussion. Please leave your concrete, constructive feedback on this proposal. +1s and other clutter posts which do not add to the discussion will be removed (use the built in functionality)
Accepted proposals are proposals that both the community and core team agree should be a part of the project. These proposals are ready for implementation, but do not yet have a developer actively working on them. These proposals are available for anyone to work on.
If you wish to start working on an accepted proposal, please reply to the thread so we can mark you as the implementor and change the title to In Progress. This helps to avoid multiple people working on the same thing. If you decide to work on this proposal publicly, feel free to post a link to the branch as well for folks to follow along.
- Any community member is welcome to work on the idea.
- The core team may consider working on this idea on their own, but has not done so until it is marked "In Progress" with a team member assigned as the implementor.
- Any pull request implementing the proposal will be welcomed with documentation and code review.
- The proposal will ever be implemented, either by a community member or by the core team.
- The core team is committing to implementing a proposal, even if nobody else does. Accepted proposals simply mean that the core team and the community agree that this proposal should be a part of this project.
Once a developer has begun work on a proposal, either from the core team or a community member, the proposal is marked as in progress with the implementors name and (possibly) a link to a development branch to follow along with progress.
Rejected proposals will not be implemented or merged into this project. Once a proposal is rejected, the thread will be closed and the conversation is considered completed, pending considerable new information or changes.
Pull Requests are the way to go, if you activly want to participate in this project.
A Pull Request may be one of the following types:
- solutions for an open (or new) Issue
- bugfix
- new feature implementation
- code parts / snippets for a related Issue
- improvement of code
- new documentation / documentation changes
- anything else relevant to the project
A Pull Request doesn’t have to represent finished work. It’s usually better to open a Pull Request early on, so others can watch or give feedback on your progress. Just mark it as a “WIP” (Work in Progress) in the subject line. You can always add more commits later.
The basic steps to creat a Pull Request are the following:
- Fork and clone the repository
- Create a new branch:
git checkout -b my-branch-name - Make your change and remember to add tests
- Build the project locally and run local tests
- Push to your fork and submit a Pull Request
- Include needed information or documents, stick to the Pull Request template.
- Update the docs (if needed)
- Put your self on the back and wait for your Pull Request to be reviewed and merged.
Here are a few things you can do that will increase the likelihood of your Pull Request being accepted:
-
Follow the styleguide in our coding manifest.
-
Write tests.
-
Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, submit them as separate Pull Requests.
-
Write good commit messages.
-
Do submit one Pull Request to address one Issue.
-
Do submit two Pull Request to address two Issues.
-
Do submit Pull Requests for typo fixes in documentation or comments. This is the easiest and most welcome way to get your name added to the contributor list.
-
Do not submit a large surprise Pull Request. Discuss the need for it and the merits of your approach first in an Issue.
-
Do not be surprised or get upset when you ignore the above and your Pull Request gets closed.
-
Do not expect all Pull Requests to lead to being merged.
-
Do not expect others to coach you through your Pull Request.
After you submit a contribution, one of the following will happen:
-
Someone requests changes to your contribution. It’s common that you’ll be asked to make changes to your contribution, whether that’s feedback on the scope of your idea, or changes to your code. When someone requests changes, be responsive. They’ve taken the time to review your contribution. Opening a Pull Request and walking away is bad form. If you don’t know how to make changes, research the problem, then ask for help if you need it. If you don’t have time to work on the Issue anymore (for example, if the conversation has been going on for months, and your circumstances have changed), let the maintainer know so they’re not expecting a response. Someone else may be happy to take over.
-
Your contribution gets accepted. You’ve successfully made a contribution to our project!
-
Your contribution doesn’t get accepted. Your contribution may or may not be accepted in the end. Hopefully you didn’t put too much work into it already. If you’re not sure why it wasn’t accepted, it’s perfectly reasonable to ask the maintainer for feedback and clarification.
-
You don’t get a response. As we are all trying to balance our work-life ratio, please give us some more time to catch up with your request.
Committers/reviewers will be added to a CONTRIBUTORS.txt file.
This open source project contains the following types of people:
-
Author: The person/s or organization that created the project. The association itself.
-
Owner: The person/s who has administrative ownership over the organization or repository. The association itself.
-
Maintainers: Contributors who are responsible for driving the vision, managing the organizational aspects of the project and handle contributions. (They may also be authors or owners of the project.) The Project Engineering Committee, described in the Governance Charter will execute this tasks with defined sub roles:
- Integration Manager Is responsible for handling and validating pull requests regarding the contribution guidelines and the overall strategic scope.
- (Dictator, if any)
-
Contributors: Everyone who has contributed something back to the project.
-
Community Members: People who use the project. They might be active in conversations or express their opinion on the project’s direction.
The best way to get in touch with us is directly via GitHub.
Also feel free to write us an email: [email protected].
If you have any questions please contact us directly via GitHub.
- Issue tracker: Where people discuss issues related to the project. For issue tracking and communication at this OSS project the build in GitHub issue section is the center of communication for all bugs, features and discussions.
- Pull requests: Where people discuss and review changes that are in progress.
- Discussion forums or mailing lists: Some projects may use these channels for conversational topics (for example, “How do I…“ or “What do you think about…“ instead of bug reports or feature requests). Others use the issue tracker for all conversations. For now there is no specific forum set up.
Currently there are no specific third party tools for communication or issue tracking in use.