A public repository, in the context of platforms like GitHub, GitLab, or Bitbucket, refers to a code repository that is publicly accessible and viewable by anyone on the internet. These repositories are open to the public, and the source code, documentation, and other related files are available for anyone to inspect, download, or contribute to. Access permissions for a public repository typically allow anyone to view and access its contents without requiring approval from the repository owner.
Setting up a repository is essential in managing and organizing digital files and documents. Whether for personal use or within a business or organization, having a well-structured repository makes it easier to access, share, and collaborate on files. This checklist is divided into two parts: Repository Development and OS Project Development. So, we will cover the important steps and considerations for setting up a repository, including choosing a suitable platform, organizing files and folders, establishing access controls, and implementing best practices for file management. We will also look at the benefits of a well-maintained repository, such as improved productivity, better collaboration, and enhanced data security. Whether you are new to setting up a repository or looking to improve your existing system, this checklist will provide you with the knowledge and tools to create an efficient and effective digital file management solution.
Set the repository's visibility to the public to make it accessible to everyone. Enable forking and cloning to allow users to create their copies of the repository for experimentation and customization. Enable pull requests to facilitate code contributions from other developers. Enable discussions to foster open communication and collaboration among contributors.
Consider implementing branch protections for projects that are vulnerable to spam. To lessen the possibility of spammy or malicious PRs, GitHub lets you set branch restrictions and even limit access to only those who have been granted explicit permission.
A README.md file, which should be located in the root folder, has information that visitors to the repository should read. A readme's contents ought to include information like this:
A CONTRIBUTING.md file is different from a readme because a contributing file details all the necessary information needed for anyone who wants to contribute to the repo.
Since it’s all about how to contribute to the repo, the file should have details such as:
This file establishes the standard for how users will see your repository and provides detailed information on the rules that should be adhered to.
If you don't have a contributing file, anything goes, and if someone submits a pull request that isn't up to par, you won't have anything to go back to. If someone submits anything that isn't up to par, you can always point them toward the contributing file if you've provided clear instructions for contributing. GitHub will even notify users to read the contributing file when they are on a page within the repository that suggests they should consider contributing.
Remember that not everyone who wants to contribute has experience with GitHub or open source. Thus, ensure that the directions are sufficiently explicit to explain what must be done.
The LICENSE.md file outlines the permissions and restrictions for using your code and other content. It is important to include a license, whether you want to allow unrestricted use or impose specific limitations. If you prefer to give people the freedom to do as they wish, a license such as MIT may be suitable.
The CODE_OF_CONDUCT.md file outlines the social norms, rules, and responsibilities that project participants should adhere to, fostering a friendly and respectful environment for collaboration. By implementing these files, your repository will become more accessible and comprehensible, leading to an increase in contributions.
A CODEOWNERS file designates one or more users who will be accountable for code in a specific section of your repository. As stated in the repository settings, these individuals will be automatically asked for review when someone opens a pull request that alters the code they are responsible for.
A CITATION.cff file can be added to a repository to provide citation information for others. It is a plain text file that is both human- and machine-readable. By adding this file to the repository, a link labeled "Cite this repository" is automatically added to the repository landing page.
When someone finds your repository through search results, the About section will give them an overview of its contents. You can link to your website or any other website that is pertinent to your repository using the URL add section. Anyone looking for these tags can find your repository thanks to the topic tags. Try your best to describe the functionality of your repository in the name. When the repository is prepared to go live, make sure it is set to public and add a social image under the settings.
Badges, also known as shields, can be used to enhance a project's readme. They can provide live development information or add a personalized touch.
Make use of technology to make the initial review procedure automated. Code style infractions, test runs automatically, and even possible security issues can be flagged by tools such as GitHub Actions. Before you even look at them, this can assist you in weeding out problematic PRs.
To run your compilers and test suites, you can find automated options in GitHub Marketplace's list of Build and Test Apps & Actions. Follow the instructions provided for your preferred tool, or use command-line scripts and arguments in your GitHub Actions workflow. Include a testing strategy in your documentation.
Define coding standards for your project. It encompasses aspects such as indentation, spacing, naming conventions, and comment usage.
Employ code linters to identify potential syntax errors, stylistic inconsistencies, and potential code smells. This helps maintain code consistency and readability.
To treat your OSS project more professionally, consider utilizing Github Projects. This tool allows you to create a Kanban board to track ideas, tasks, goals, and work progress as your application develops. This is beneficial in preventing redundant work. Additionally, it serves as a useful platform for storing and organizing thoughts and ideas for future planning.
Define a branching strategy (e.g., feature branches, Gitflow) to organize development.
Branches should always represent features to begin with. To add the ability for a user to log in, for instance, you should probably create a branch called "user_authentication" and only make the necessary updates in that branch to allow a user to log in.
When working together, your team must select features with non-overlapping code. For example, you shouldn't work on the "user_login" branch while your teammate is working on the "user_logout" branch, as you are likely to work on the same files and write code that overlaps.
GitHub Codespaces offers a fully functional and customizable development environment. This eliminates the need for someone to set up a local environment for anyone to work on your project from anywhere. All developers will be working from the same configuration in a well-configured codespace, which eliminates the "it works on my machine but not yours" issue and makes it much easier for others to contribute to your project.
The "Issues" section in every GitHub repository serves as a project board where tasks and discussions related to that repository can be organized. Any individual can submit an Issue to the repository. Typical Issues that are created on repositories may involve reporting a bug, proposing an improvement, or seeking clarification about the repository.
To maintain control, it is recommended to use Issue templates for anyone creating an Issue. Please refer to the GitHub documentation on Issue template guidelines for instructions on creating these templates.
Multiple Issue templates can be set to allow for the selection of the appropriate template based on the type of Issue being reported. Templates also enable automated actions based on the creation of the Issue. For instance, if a bug Issue is reported, it can be automatically assigned to someone.
Pull request templates allow you to establish a specific template that must be completed when initiating a pull request. Please refer to the GitHub documentation on Pull request template guidelines for instructions on how to create them.
A pull request template helps ensure that contributors adhere to the guidelines outlined in the contributing file. It can be used as a general guideline to request confirmation from contributors that they have completed basic checks, such as reading the relevant repository documentation or ensuring their submitted code aligns with the guidelines specified in the contributing file.
GitHub Labels allow you to create categories for Issues and pull requests. Applying labels allows easier scanning and filtering of Issues and pull requests by providing some visual aid. These labels include both skill labels unique to each repository and common labels. These don't need to be manually configured. It is not necessary to rename the labels because they are automatically maintained on all CC repositories.
Users and security researchers should be able to responsibly and securely report issues they find with your project. To give users and the community at large these guidelines and to help you keep their trust, include a security policy SECURITY.md file in your repository. Moreover, activate private vulnerability reporting, which enables security researchers to safely report any flaws they discover!
When assigning roles and permissions in a repository, it is important to consider the level of trust and responsibility given to collaborators. The "Read" role is for the general public, while "Triage" and "Write" are for trusted individuals within the company or working group. "Maintain" and "Admin" roles are best for core maintainers who review and manage production. Trusting collaborators with higher roles is important as they can manage issues, discussions, and comments.
Secrets are private, sensitive information that you must maintain secret, such as API keys, passwords, and certificates. GitHub's built-in secret-management tools or a third-party keystore should be used in place of directly embedding these into your code or logs.
Scanning code for vulnerabilities is a complex topic, but breaks down into three major categories:
Dependencies: GitHub Dependabot is a tool that alerts and helps fix insecure dependencies in code. It can be enabled on public repositories and organizations and also provides updates on new versions of packages.
Secrets: Secret scanning tools, available through third-party integrations and GitHub Advanced Security for Enterprises, can detect and prevent secret tokens from being embedded directly into code, even if they slip through the cracks.
Novel Vulnerabilities: Adding new code can introduce vulnerabilities to an application. GitHub Advanced Security offers code scanning to help identify flaws in popular coding languages, such as SQL injection and circular references.
To configure your sponsor button, edit the FUNDING.yml file in your repository's .github folder on the default branch. Customize the button to include sponsored developers in GitHub Sponsors, external funding platforms, or a custom funding URL.
Sponsorship tiers are an important aspect of managing sponsorships and generating support for your work. By offering different tiers, you provide potential sponsors with a range of options to choose from based on their preferences and budget. Each tier can have its payment amount, whether it's a one-time payment or a monthly subscription. Additionally, you can customize the rewards and benefits that sponsors receive at each tier, such as early access to new versions, recognition of your project, or exclusive updates. It's recommended to offer a variety of sponsorship options to accommodate different sponsor preferences and financial capabilities, as this makes it easier for anyone to support your work.
Open-source projects use various funding and monetization strategies, including OpenSaaS, Open-Core, donations and sponsorship, crowdfunding and grants, commercial support and services, and strategic partnerships. OpenSaaS involves offering a Software-as-a-Service alternative based on open-source code. Open-Core offers a free core product with premium features for a fee. Donations and sponsorships from individuals and companies also support open-source projects. However, relying solely on donations can present challenges due to unpredictable and fluctuating income.
You have a full package of important info such as README, contributor guide, code of conduct guide, etc (mentioned in this checklist above).
Use gamification solution devActivity for the open-source community to boost engagement, reactivate inactive contributors, ensure efficient onboarding, and acquire new talent. The concept involves rewarding contributors with experience points (XP) for their contributions, allowing them to earn achievements and level up. This gamification initiative focuses on tracking the number of active contributors, contribution scores, and contribution frequency as key performance indicators. devActivity also aims to reengage inactive contributors and create a seamless onboarding process for first-time contributors. Additionally, the initiative aims to attract new talent by monitoring the number of first-time contributors.
GitHub keeps impressing us as we learn more. Github lets you create automatic responses for repo actions, like sending a message when someone commits for the first time.
To provide support for your project, you can create a SUPPORT.md file in your repository. This file can be located in the root, docs, or .github folder. When someone creates an issue, they will be directed to the SUPPORT file for help. You can also create default support resources and link to the SUPPORT file from other parts of your repository.
Engaging with your community is important for creating a healthy and collaborative environment. This may include organizing meetups, maintaining a project blog, or simply engaging in discussions.
GitHub Discussions can be used in a repository or organization to facilitate conversations and share information without the need for specific issue tracking. It allows for community engagement and collaboration across multiple repositories. To enable or disable GitHub Discussions, refer to the provided documentation.
Promote the project among those who are interested in it: new contributors, customers, partners:
The Public Repo Checklist is a comprehensive guide that outlines the necessary steps and considerations for developing a successful public repository. It is divided into two parts: Repository Development and OS Project Development. In the first part, Repository Development, the checklist covers important aspects such as setting up a version control system, defining repository structure and organization, establishing guidelines for documentation and code formatting, and implementing a review process. The second part, OS Project Development, focuses on specific considerations for open-source projects, including licensing, contribution guidelines, community engagement, and maintaining a roadmap for future development.
In conclusion, following a thorough public repo checklist is crucial for the successful development of a repository and an open-source project. From repository settings and content to automation and security measures, every aspect plays a crucial role in the success of your project. By implementing this comprehensive checklist, you can ensure that your project is well-organized, accessible, and user-friendly. Remember, collaboration and transparency are key in the world of open source, so don't hesitate to share your work and engage with the community. With the right tools and a well-executed checklist, you'll be well on your way to creating a thriving and impactful open-source project.