The first thing you’ll want to do is create a GitHub repository to house your project code and documentation. Choose a clear and descriptive name for the repository that conveys what the project is about at a high level. Some common conventions to follow for the repository name include the format “project-name”.
Once the repository is created, you’ll want to add a high-level README.md file to introduce visitors to the project. The README should include the project title, a brief description of what the project does, why it was built, and how to setup and run the project locally. It’s also good to include any documentation, installation instructions, important links, and credit required libraries, frameworks or tools used. Well documented README files help provide valuable context and onboard new contributors.
You’ll also want to add a LICENSE file to indicate the type of license the project is released under. Common choices for open source projects include MIT, Apache 2.0, and GPL. Adding a license prevents legal issues and clearly states how others can use and contribute to your work.
Create a directory structure that logically organizes the project code and resources. Common top-level directories include “docs” for documentation, “src” or “code” for source code, “test” or “tests” for automated tests, and “data” or “resources” for additional project assets. Keeping a simple and consistent structure makes the project easier to navigate and understand.
Within the code directory, further divide source code into logical modules with meaningful names based on their purpose. For example, separate code for the backend API, frontend UI, CLI, database integration etc into their own subdirectories. Grouping code type and functionality helps isolation and organization.
For any programming language specific files like a Gemfile, package.json, requirements.txt etc, be sure to include those in the root directory so required libraries and tools are defined upfront and easy to discover.
Documentation is extremely important for others to understand how to contribute to the project. Consider adding detailed documents in the docs directory explaining:
Project architecture and overview – Explain the high level design, assumptions made, and technologies used to build it.
Getting started guide – Steps to setup the development environment, run/build the code, and understand the workflow.
Design documents – Explain the architecture, data model, APIs and important design decisions made.
API documentation – If the project exposes any external APIs, generate API documentation explaining available endpoints, parameters, response formats etc.
Testing philosophy – How the project is tested, recommended testing practices and how others can add or modify tests.
Contribution guidelines – How others should contribute code/bug fixes back to the project through pull requests following code style, commit conventions etc.
You’ll also want to setup continuous integration (CI) to run automated tests and checks on all code contributions. Popular free services for open source projects are Travis CI and Github Actions. CI increases quality by running validation and preventing broken code commits.
Consider adding a changelog to track releases, features added, bugs fixed per release. This gives insight into the project progress and changes over time.
Proper documentation and code organization takes extra effort upfront but pays significant dividends later by lowering the barrier for new contributors to understanding and participating in the project. A well presented project attracts more community involvement and ensures it can be maintained long term. Following standard practices and conventions when establishing your capstone project on GitHub makes ongoing development and collaboration smooth.
Andrew Stroud