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.
A new developer should be able to build the system without obtaining additional files from you.
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/
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 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:
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.
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.
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.
Overview. Summarizes what the system does and what makes it special and different from other related applications.
User Guide. Provide at least one screen shot of every page. This section should provide enough detail for a user to get up and running with your system (you can provide further help within the application itself).
Community Feedback. Provides information obtained from users about the system.
Developer Guide. How to download, install, and run the system locally, as well as how to deploy it.
Development history. Explains the trajectory of development of the system: what was accomplished during each milestone. See the BowFolios system for details.
Contact Us. Explains who the developers of the system are and how to get in touch with them if you have comments or questions.