A How to Guide for New Contributors

A How-to Guide for New Contributors

Going from a user and/or project observer to an active contributor of any open source project is oftentimes the most difficult step. But once that hurdle is cleared, each contribution thereafter becomes increasingly easy. This how-to guide will help lower the barrier to entry for new developers that are just getting started with the project. Although numbered, this is a loosely-organized how-to guide, rather than a step-by-step. The order in which the items are presented are for your convenience and a suggestion for how to approach this project.

0. Prerequisite Knowledge

OpenBoard is built primarily on c++, and also relies heavily on the use of JavaScript, with some html and css elements. Knowledge of the following supported programs are also recommended: Windows, OSX, and Linux. The source code repository is located on Github, which you should have basic knowledge of, specifically how to clone, branch, commit, push, and make pull requests.

1. Get Familiar With the Project

We recommend all contributors familiarize themselves with the OpenBoard project by using it. First-person experience is invaluable to understand how the program works, as seen from the user's perspective. You can install the software on Windows 7+, macOS 10.9+, or Linux Ubuntu.

Here is a link to the executable files for all platforms: https://openboard.ch/download.en.html

2. Clone the Repository

Now that you've successfully installed OpenBoard to your machine, hopefully you have a better understanding of how the software works for the end user. The next step is to clone the repository to your local machine.

Navigate to the OpenBoard Github page at: https://github.com/OpenBoard-org/OpenBoard

3. Learn the Settings

There are two (2) configuration files that you should be familiar with: OpenBoard.config and OpenBoardUser.config. These files control the program's global settings and user settings, respectively. The location of these files for each platform can be found at the link below.

Note: The configuration files will automatically generate at these locations when you run the program for the first time.

For more help on settings and the syntax used therein, go to: https://github.com/OpenBoard-org/OpenBoard/wiki/Settings

4. Resolve an Issue or Add a New One

If you're able to make a code contribution, we have a running list of issues on GitHub that is contributed by our users. Remember, that "issues," are not exclusively bugs, but also cover new feature requests. As a contributor, you're expected to be familiar with the user-facing aspect of the software, so it's not uncommon to contribute to the list of issues after using/testing the application for some time--Just be sure to browse the issues before adding a new one.

Browse the running list of issues on the GitHub page: https://github.com/OpenBoard-org/OpenBoard/issues

5. Branch and Code

Once you've cloned the repository and are ready to help resolve an issue, create a new branch. We don't yet have specific coding guidelines for contributors, but we loosely adhere to this Open Source Guide: https://opensource.guide/

Be sure to comment your code thoroughly and attribute your name in the comments for any modifications that you make. Document the technical changes in the commit comments, and be sure to reference the issue number when making a pull request.

6. Test Thoroughly

In order to avoid patch rejection, you are expected to test your code very thoroughly and compile the program. Any code contributions that throw errors or cause the program to fail will immediately be rejected. Since it is your responsibility to test your own code, we will not attempt to troubleshoot, nor find any errors in the code.

7. Make pull request

After you have thoroughly tested your code and concluded that the issue has been resolved without introducing new bugs, it's time to make a pull request. When making a pull request for your branch, indicate the issue number and a brief explanation of how you resolved it.

8. Get Support

We don't have an official communication medium that is exclusive to developers, but our core team has an active presence on this support forum: https://openboard.ch/forum/. Most posts are from end users, but we welcome developers in this space for communication.