GitHub hosting guidelines for project management

GitHub provides excellent support for hosting open source projects if you know how to utilize the features. Here are some guidelines to help ensure you make the most of it.

Host all source code…

A new developer should be able to build the system without obtaining additional files from you.

…but do not host “derived” files.

Hosting all source code does not imply that all code is hosted. In general, do not host “derived” files: code that can be automatically generated from source code. For example, the “node_modules/” directory should not be committed to GitHub and instead should be generated locally by each developer by running npm install.

To avoid hosting derived files, create a .gitignore file in the top-level directory of your project. Here’s an example:

# .gitignore standard file for ICS Software Engineering Meteor Development.

# Ignore IntelliJ Project files.
*.iml
.idea/

# If on a Mac, ignore DS_Store.
.DS_Store

# Don't commit the production settings file.
settings.production.json

# Build node_modules locally.
node_modules/

Create a GitHub organization for team-based development.

Your team should come up with a name for the application under development, which will also be the name of the organization. Note that you will have to come up with a name that has not been previously taken as a GitHub organization.

Make sure your name is appropriate and professional, since you’ll want to include this project in your professional portfolio.

Let’s say your application name is “Toaster Oven Lovin”, and that toaster-oven-lovin is available as a GitHub organization name.

One member of your team should:

• Create a GitHub organization called “toaster-oven-lovin”.
• Create a team in that organization called “developers”.
• Invite all the other members of the team to that organization.
• Give all team members “owner” status, so they can create, delete, and push to repos.

Create the project home page in {organization}.github.io.

Create a README.md file in your {organization}.github.io repository, and use the “Automatic Page Generator” facility found in the Settings menu for that repo to create a home page for your project based upon that file.

For example, if your organization name is toaster-oven-lovin, then:

1. write a README.md to document your application in the toaster-oven-login.github.io repository.
2. Load it as the source in the Automatic Page Generator facility

After that, https://toaster-oven-lovin.github.io will display a nicely formatted home page for your project.

Note: each time you change the README.md file contents, you must “republish” the GitHub page version and reload the README.md file as the source. It does not automatically update with the latest version of the README.md.

Design a tagline

When you use the automatic page generator, it will provide you with text field in which to provide a “tagline”. Do not waste this text on something like “Home page for the Toaster Oven Lovin application.” That’s serves no purpose: visitors already know that they are at the home page! Instead, design an actual tagline for your application. For example, for toaster oven lovin, a tagline might be: “Nutricious. Delicious. Cheap. For and by UH Students.” (Don’t use this; you can think up something better.)

Develop the application in a different repository.

Do not develop your application inside the {organization}.github.io repository. Instead, create a second repository to hold the application code.

In many (but not all) cases, the organization and the application have the same name. For example, in the case of toaster-oven-lovin, you might end up with two repositories:

• toaster-oven-lovin.github.io
• toaster-oven-lovin

One of the benefits of creating an organization is that you can easily create additional repositories as your project grows, all underneath the “umbrella” of your organization.

Create a README.md to document your project.

For small applications, the README.md file should provide all of the required documentation for the system (outside of code-level documentation). Your README.md file should contain the following sections.

• Introduction. Summarizes what the system does. It should include at least one screenshot. It should also explain what makes it special and different from other related applications.

• Installation. Explains how to download, install, and (if necessary) deploy the system.

• Usage. Explains how to use the system. You should provide at least one screen shot of each page in your application, along with explanations of what each page accomplishes. If the application is deployed, this section should provide a link to the deployed version.

• Development. Explains how to set up an appropriate development environment for the system, and how to run any quality assurance tools provided as part of the application.

• Contact Us. Explains who the developers of the system are and how to get in touch with them if you have comments or questions.

For examples of README files, check out Awesome README. In addition, How to write a great README provides more suggestions.

In the case of our example toaster-oven-lovin project, this README.md file is hosted in the toaster-oven-lovin.github.io repository. The README.md file for the toaster-oven-lovin repository can just be a single line that directs the user to the project home page for details on the project.