In the next few days I will start coding my first ever open source project. I am looking for suggestions/tips on how to structure the GitHub repo, what licenses the project should use and any best practices I should implement from the get-go to make a project that is well structured for other people to contribute to. I am in the UK and when the beta is done I plan to create a charity that will ‘own’ the project and IP like the domain.
I got this book for free at a hackathon a while back. https://producingoss.com/ It does a good job of outlining the areas of maintaining the project that require more than just technical skill.
Ezri said:
I got this book for free at a hackathon a while back. https://producingoss.com/ It does a good job of outlining the areas of maintaining the project that require more than just technical skill.
Thank you 
Congratulations on starting your open-source journey! Structuring your GitHub repository and implementing best practices early will make your project more approachable for contributors. Here are some tips:
1. GitHub Repository Structure
- Root Structure:
├── src/ # Source code
├── docs/ # Documentation files
├── tests/ # Unit or integration tests
├── .github/ # GitHub-specific files like workflows
│ ├── ISSUE_TEMPLATE/
│ └── PULL_REQUEST_TEMPLATE.md
├── LICENSE # License file
├── README.md # Overview of the project
├── CONTRIBUTING.md # Contribution guidelines
├── CODE_OF_CONDUCT.md # Expected behaviour from contributors
└── CHANGELOG.md # Track changes across versions
- Key Files:
- README.md: A clear introduction, goals, setup instructions, and contribution guidelines.
- CONTRIBUTING.md: How people can contribute (e.g., coding standards, creating issues, submitting PRs).
- CODE_OF_CONDUCT.md: A statement of values and expected behaviour for contributors.
- CHANGELOG.md: Helps contributors and users track project evolution.
2. Licensing
Recommended License:
-
MIT License: A permissive license, widely adopted and simple to understand.
-
GNU GPLv3: Ensures derivative work remains open-source (good for ethical projects).
-
Apache License 2.0: Permissive but provides an explicit patent license.
-
Steps:
- Choose a license from ChooseALicense.
- Add a
LICENSEfile to the root of your repository.
3. Best Practices
- Use Semantic Versioning: Adopt Semantic Versioning
(e.g., v1.0.0)for your releases. - Write Clear Documentation:
- Start with a user-focused README.
- Create a
docs/directory for detailed setup, API references, and advanced topics.
- Automate Testing:
- Include basic tests from the start and integrate them into GitHub Actions for CI/CD.
- Tag Issues for Contributors:
- Use tags like
good first issueorhelp wantedto encourage contributions.
- Use tags like
- Set Up GitHub Actions:
- Automate checks, tests, and deployments.
- Design a Logo: Even a simple logo adds identity and professionalism.
- Encourage Discussions:
- Use the GitHub Discussions feature for feedback and brainstorming.
4. For Long-Term Vision
- Plan IP Transfer: Work with a solicitor familiar with UK charities to establish clear ownership of the IP under the charity when it’s created.
- Engage with the Community:
Join forums and open-source meetups to share your project and attract contributors. - Create a Project Roadmap:
Publish a high-level roadmap to communicate your vision and planned milestones.
Skyler said:
@Thorn
Thanks*, ChatGPT!
Gpt don’t give the right info until the prompt is correct, + you have to maintain the markdown structure yourself.
Write the documentation first.
Keep your repo organized with a clear README.md, a license like MIT, and simple contribution guidelines. Document setup and usage early, and share your vision for involving a charity to attract contributors.