ICS 314 Fall 2024

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 VSCode settings files.
.vscode/

# 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 the project home page in {organization}.github.io.

Create a index.md file in your {organization}.github.io repository, and use the “GitHub Pages” 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 index.md to document your application in the toaster-oven-login.github.io repository.
  2. Select a theme using “Theme Chooser” and click “Publish” to publish it.

After that, https://toaster-oven-lovin.github.io will display a nicely formatted home page for your project, and updating and committing the index.md will update your home page documentation.

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:

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.

Document your project.

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