openframeworks / openframeworks/openFrameworks
Add examples/README.md to explain and provide steps to create missing project/make files
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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