Examples Contribution Process Flow

Jeff Gray edited this page Feb 20, 2016 · 9 revisions

Quick Links - Inline Commenting Guide | README Guide | Overlay Text Guide | HOT LIST

If you're reading this, hopefully you're interested in helping make openFrameworks' examples even more useful, informative and self-describing, so they can be used most effectively with new and returning users. This document is a result of the oF Doc Sprint that took place at EDP in Denver, CO, February 17-20, 2016.

TL;DR - We're adding more context. To help out, skip down to How to Help to see recommended flow for adding to the documentation and staying consistent with the templates we've built.

Here's the active list of examples that have been claimed, completed, and are yet to be cleaned up.

What's Changing

To expand the usefulness of the examples, we're focusing on three main areas where Examples can be expanded. Below these are outlined, with a bit of our thinking behind each of the three.

In-line Code Commenting

The most direct, and least change-heavy of the three, we're combing through the Examples, expanding the existing in-line comments, primarily in the implementation file(s) of the example (.cpp, .mm) except for where specific actions taken in the .h files are of importance to the example in question.

README readme readme, Everywhere

Fully embracing the power of Github, where the project is hosted, we're creating README.md files in the root directory of each Example. We're also organizing the examples more contextually and providing category README.md files. This provides "landing pages" when browsing through the code on Github that can give you additional notes about the example without bloating the source files directly, and is also quite human readable when viewing locally on your computer. Additionally, we are dropping a screenshot .gif, .jpg, or .png alongside each README to provide a quick view of the application, making it easier to find that example you've used in the past and need again.

Overlay Runtime Text

Finally, we're attempting to make overlay text consistent across examples where it can be useful. This text will appear on top of the sketch at runtime, and will universally be toggleable by the h (for help) key. This gives additional contextual information to the user, in a consistent fashion, and is the go-to location (along with the README.md) for listing the function of keys, clicks, and events in the example. To note, this is not being implemented in iOS/Android examples given the differences in keyboard functionality in mobile.

How to Help

Instructions are aimed to make these changes as frictionless as possible for the project maintainers in Github.

1. Fork the openFrameworks Repository

Step 1

2. From Your Forked Repository, Make a Branch

Step 2 Create a branch for a specific example, so that it can be easily reviewed and accepted into the openFrameworks' project without changing something outside of that example's folder. (exceptions would be if you're editing the categories themselves or using git mv to rearrange where an example exists.

3. Commit Your Changes, Push/Sync with your Forked Repo

Commit early, commit often, you're working in a branch specifically for this task. Go crazy. When you're feeling good about your work, and have pushed it up to your repo (or synced, if you're using the Github app), continue to final step...

4. Sync Upstream Changes from the openFrameworks Repository

To make a PR as easy as possible to accept by maintainers, make sure to merge the most recent master branch of the openFrameworks repo to your branch. Instructions and best practices for this are location here.

5. Create a Pull Request for Submission to the openFrameworks Repository

Step 5-1 Click on "Pull requests" tab...

Step 5-2 Click on the "New pull request" button...

Step 5-3 Confirm the base fork belongs to openFrameworks and is pointing to the master branch, and the head fork is pointed at your fork with the branch you just did work in selected. Then click on the "Create pull request" button.

Step 5-4 Provide as detailed information as you can for your changes, so that its as easy as possible for the maintainers to understand your additions.

Upon clicking on "Create pull request", you'll be alerted if there are any comments/questions on your PR, and/or if its accepted into the code-base.

To note, please check out these docs for more information on the openFrameworks git workflow, the openFrameworks Coding style guidelines and the Issue and pull request management details document.

That's it! Thanks in advance for helping keep openFrameworks great!