This repository serves as a guide on how to do Open Source Software (OSS) projects on GitHub.
Other commonly used terms are
- Free and Open Source Software (FOSS)
- Free/Libre and Open Source Software (FLOSS)
Open source software is software licensed under an open source license.
The Open Source Initiative defines criteria for open source software and lists all licenses that are considered open source licenses.
If you are not sure which license you should chose have a look at Choose a License. It helps you to find a license that is aligns with your intent of openness.
Examples: GNU General Public License (GPL), Affero GPL (AGPL), Lesser General Public License (LGPL), or Eclipse Public License (EPL)
Examples: Apache, MIT, or Berkeley Source Distribution (BSD)
For creative work such as text or images you can use a creative commons license: Creative Commons
The README is the first thing that people see when they visit your repository. Thus, a good README invites people to explore your repository and use your software.
A good README should contain at least the following information:
- A brief introduction to the project
- Instructions on how to build, test, and run the project
- License information
See my template: README.md
If you want to include diagrams in your README file you should use plain text formats if possible. Binary formats are not suitable for version control systems such as Git, which results in a not transparent change history.
Examples for plain text representations:
A comparison between different plain text formats for diagrams can be found here: https://text-to-diagram.com
Continuous integration (CI) and continuous delivery (CD) are software development practices that help to automate the build, test, and deployment process. Providing a feedback loop for developers and users. Since the build process is executed in a virtual environment, it is reproducible and independent of the local development environment. Missing dependency declarations are detected early through the clean virtual environment.
Further, it is a form of documentation, because it shows how to build, test, and deploy the software. This way, you can't forget how to perform a complex build or deployment process.
In GitHub, CI/CD is implemented as GitHub workflows and actions.
Tasks that should be automated with workflows and actions:
- Testing
- Building
- Linting (ensure consistent code style)
- Deployment (e.g., as Docker image or to a cloud provider)
File that represent credentials or secrets should never be committed to the repository, even if it is a private repository! If you need to store credentials or other secrets in your repository, you should use GitHub secrets.
In the following example, the google-services.json file is created during the CI process from a GitHub secret.
The content of the file is not stored in the repository and is now shown in the logs of the CI process.
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Copy google-services.json file
run: echo "$GOOGLE_SERVICES_JSON" >> google-services.json
env:
GOOGLE_SERVICES_JSON: ${{ secrets.GOOGLE_SERVICES }}Pull requests (also known as merge requests) are a way to propose changes to a repository. They are also a way to discuss changes via comments and reviews. If you are not part the owner or a collaborator of a repository, pull requests are the only way to contribute to a repository.
You can setup GitHub so that you need one or more review(s) before a pull request can be merged. This is often done in organizations to ensure code quality and inform others about changes.
Similar to the size of a commit, a pull request should be as small as possible. This makes it easier to review and understand the changes.
Issues are not only to report bugs, but also a simple way for project management and coordination, e.g., to discuss new features or improvements.
You can use issues to manage
- To-do lists
- User stories
- Discuss ideas and design decisions
- Feature requests
- Answer questions
GitHub provides a list of issues that are suitable for beginners: GitHub topic
This is a great opportunity to get started contributing to open source software.
Copyright © 2023 Andreas Bauer
This work is licensed under CC BY-SA 4.0.