openframeworks / openframeworks/openFrameworks

Add examples/README.md to explain and provide steps to create missing project/make files

Open
#4,183 10 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

core documentation feature waiting-for-feedback
Dominant language
C++
Stars
10.4k
Forks
2.6k
Avg merge
1d 21h
Merged PRs (30d)
9

Description

An issue that seems to trip up users new and old seems to be the missing example project files. I cannot count the number of times I've tried to help a user out on IRC or the forum that has run into this and I really feel as though we are making things more difficult for end-users. The main README.md does reference the issue:

If you are working with the Git repository, the stable branch of the OF repository corresponds to the most recent release, with a few important differences:

3. This GitHub repository has no project files for the different examples. They are generated automatically for each release using a tool in apps/devApps/projectGenerator/.
If you want to work with the openFrameworks GitHub repository, you should use the project generator to create project files for all the code in examples/.

but this isn't particularly helpful as it is hiding behind a "developers" badging (What if they are just a user and not a developer? Does it mean developers of openFrameworks proper or developers of applications using openFrameworks?), this probably isn't descriptive enough for new users and this doesn't help users that downloaded a repo archive via GitHub.

I suspect there are good reasons for not having the project/make files in the repo itself (though if it is file size, one could argue a couple of MB of project files pales in comparison to the trillion MBs of third party dependencies 😉) but I think it would be kind to pull out the issue to top billing in the main README and create a secondary README right in the examples folder as well. I am a bit behind on the current state of PG, command-line vs GUI, submodule vs inline, so I'm not in a great position to offer the README tweaks, but I do think it is an issue I'd hope could be considered for 0.9.0 if others felt important.

Note: the examples/README.md would probably need to be stripped for the nightly builds.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the Developers section of README.md and the project generator under apps/devApps/projectGenerator/ to confirm the current command-line, GUI, and repository workflow. Add examples/README.md and improve the main README guidance so users can create missing project or make files, while checking how nightly builds should handle the added file.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
build-system, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.