Project Checklist

All content (source code, docs, images, sound, etc) must be either

• Original content, written from scratch by you

• Content from elsewhere that is

  • Clearly marked with where it came from

  • Legal and ethical for you to use

You must have a README.md file (in Markdown format) containing at least:

• Your name(s)

• Your project name

• A description of your project (1-2 paragraphs, enough so that people know what it is, what it does, how it works)

• A description of how to build, install and run your program, or links to documents elsewhere in your project that describe this

• An example illustrating the operation of your code

  • A screenshot or demo run for an application

  • Some example code for a library

• License information, including a pointer to the LICENSE file

Make sure the project Issue Tracker is set up

You must have user and/or developer docs sufficient to let end users work with the software and/or developers understand it

You must have a LICENSE text file in the root directory of your project containing license information. A link/URL is not OK: you need a copy of the license that is under your control

Your build instructions should include:

• Checkout and download instructions
• Prerequisites for build
• Build instructions
• Installation instructions

Code

• Source code should be in a sensible place: either in the root directory or in some subdirectory mandated by the build environment (for example, the src/ subdirectory for Cargo projects). There should not be an extra layer of directory between the top level and the source code for no good reason

• Binaries, when needed. Consistency with SCMS and platform make this a bad idea unless it's unlikely that your users could build the software. Good example is Android apps, for which you'll need a current .apk. Use the Release feature of GitHub or GitLab for these

• "Release" commits should be Git tagged

Validation and Verification

• If tests are present, they should be automatically runnable, and a test report should be present

• The project pull request history may serve as documentation of project inspection. Include documentation of other ways in which the project has been inspected

"Junk" files must not be checked into the repository. Junk files include:

• Build artifacts (for example, .o files and executables)

• Editor and IDE junk: "~-files", Mac "hidden" files, IDE artifacts, etc. (If your project can/should/must be built with an IDE, it is reasonable to check in the project file itself, but the other stuff not so much.)

• Backup files, junk directories, old versions of the project, etc.

In short, somebody cloning your repo should get exactly what they need to build and work on your code, and absolutely nothing else