Thank you for your interest in contributing to the OpenBoxes project! We're glad you're here. We feel that every use case is different, and that using the community to steer us by accepting contributions from a broad range of individuals and organizations will ultimately result in a better tool for all of us.
If you need support for OpenBoxes, please check out the documentation, and if you still have questions, checkout the support forum here, or chat with us live on Slack. We're happy to help!
If you've found a bug in OpenBoxes, please open an issue.
If you've got something you want to share, whether it's a bug fix or some new documentation or whatever, continue reading below!
Yeah, reading documents like this takes a long time, but we feel that having a common understanding of the goals and expectations of contributions saves more time in miscommunication and recreation of pull requests than it costs up front. It's short, we promise!
We need help with a lot of things to keep the project moving along. Here are a couple:
- Writing unit and web automation tests
- Writing bug reports when things don't work right
- Improving the documentation, especially the user guide!
- Writing tutorials for basic workflows in OpenBoxes
- Recreating existing bug reports to help provide more information
- Bug fixes!
- New features!
- Talk us up on blogs, social media, etc
While the above are the common ways we see members of the community contribute to the project, we've got open minds, so if you want to contribute in another way, we'll probably be on board with that. Let's talk about it!
- Be respectful of others. We're all human and we're all working towards the same goal.
- All Groovy code submitted should adhere to the official style guide.
- All generated HTML and CSS content should properly validate (html, css).
- Pull requests should always be squashed.
- All code submissions should be covered by included unit tests. All unit tests must pass.
- Before starting work on a PR for a bug or feature or documentation, please open an issue to discuss it.
- All contributions have their copyright assigned to Partners In Health and are licensed under the Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php).
- Be welcoming of newcomers! Our community is improved by having more contributors and users, so let's encourage them to stick around.
Unsure where to begin contributing? If you've played around with OpenBoxes, you've no doubt come across a few places where the documentation is a little lacking. We often get so caught up in bug fixes and feature requests that the documentation can lag behind. Write a glossary, or an explanation of how the Stock Card works, or what the different options on the dashboard mean. Explain how to set up locations, parties, and users. Really, anything would be helpful!
If you've got a mind for code, you could also head over to our bug tracker and find an open issue. Find something that you think you can handle, discuss it with the reporter and other devs, and then go write a fix and make a PR. We love PRs!
To set up a development environment for hacking on OpenBoxes, please see the instructions in the readme.
The idea of giving away software code for free may seem strange at first, but it's a great way to make the world a better place! OpenBoxes has users all over the world who are looking forward to your next contribution. If you're not sure how the open source philosphy works, here are some links to get you started:
At this point, you're ready to make your changes! Feel free to ask for help; everyone is a beginner at first 😸
If a maintainer asks you to "rebase" your PR, they're saying that a lot of code in the project has changed since you started your work, and that you need to update your branch so it's easier to merge.
- Create your own fork of the code
- Do the changes in your fork, following the notes above
- If you like the change and think the project could use it, send a pull request!
For detailed instructions please see Contributing a Pull Request on our wiki.
When filing an issue, make sure to answer these five questions:
- What version of OpenBoxes are you using? It's in the footer of the web interface.
- What operating system and browser are you using?
- What did you do? Please include steps so that we can reproduce the problem.
- What did you expect to see?
- What did you see instead?
- Screenshots and videos are extremely helpful! Please include some!
If you find yourself wishing for a feature that doesn't exist in OpenBoxes, you are probably not alone. There are bound to be others out there with similar needs. Many of the features that OpenBoxes has today have been added because our users saw the need. Open an issue on our issues list on GitHub which describes the feature you would like to see, why you need it, and how it should work.
The core team looks at Pull Requests on a regular basis. Hopefully any major considerations have been ironed out during the discussion on the issue (you created an issue before you made the PR, right?), so any comments on the PR will hopefully be in regards to the specifics of the implementation. If we see any adjustments that need to be made, we'll let you know, and hopefully it can get merged for the next release!
If you actually read this document, you get a gold star! We're happy you're interested in helping make OpenBoxes even better. :)