What is a Public Repository?

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

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.

PART I. Repository Development

Step 1: Repository Settings

1.1. General Settings

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.

1.2. Limit Access

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.

Step 2: Repository Content

2.1. Repository README File

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:

• Description of what the repo is about.
• Technologies, libraries, and frameworks used.
• How to install and use the contents of the repo.
• The current state of the repo.
• Any other essential info you want the reader to know.
• GIF demo of the project.

Examples:

1. aregtech/areg-sdk - It includes logos, badges, a list of contributors and stargazers, a table of contents, navigation links, headlines with graphics, a menu to hide/show topics, project description, and philosophy, instructions for cloning and integrating, multiple tools for quick building, configuration instructions for the tools, references to examples and demo projects, references to using cases, links to contact and share the project on social networks.
2. emalderson/thephish - It includes a logo, badges, table of contents, description, screenshots, installation guide, contributor guidelines, code of conduct, UML diagrams, tags, issue and pull request templates, well-documented and commented code, and examples.
3. refinedev/refine - It includes a clean project logo, with a brief description, multiple badges, usage description and examples, use cases and demo links, screenshots, key features, contributors, stargazers, and contribution guidelines.
4. AntonioFalcaoJr/EventualShop - It includes a logo and well-defined sections with information, architectural solutions, and reference links. It provides instructions for running the project in different environments and includes load tests, technology descriptions, and diagrams.
5. Martinsos/edlib - It includes a brief overview of informative badges and their purpose. It mentions the need for concise descriptions, feature lists, table of contents, screenshots, and instructions with examples. It also highlights the importance of common code examples to facilitate quick project implementation.
6. Stack-in-a-box/triumphmayflowerclub.com - It includes a website that is designed to be accessible for beginner developers and provides clear instructions. It is described as having a friendly and inclusive tone with common elements found in other attractive READMEs.

Tools:

1. README - Maturity model.
2. readme-md-generator - A CLI that generates beautiful README.md files.

2.2. Repository CONTRIBUTING File

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:

• Kinds of contributions do you accept (bug fixes, enhancements, documentation updates, etc).
• Instructions for submitting a contribution (by submitting a pull request).
• Guidelines for code submitted (linting rules, file naming, variable naming conventions, etc.)
• Any other instructions or guidelines you want a contributor to follow.

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.

Examples:

1. antoinezanardi/werewolves-assistant-api-next
2. Redocly/redoc
3. teles/array-mixer
4. ryanoasis/nerd-fonts
5. cookiecutter/cookiecutter
6. rubygems/rubygems.org

Tools:

1. Contributor file generator.

2.3. Repository LICENSE File

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.

Examples:

1. zenml-io/zenml - Apache License 2.0.
2. supunlakmal/thismypc - MIT License.
3. sr6033/lterm - GNU General Public License v3.0.
4. php-censor/php-censor - BSD 2-Clause "Simplified" License.

Tools:

1. You can visit choosealicense.com to get guidance on selecting the most suitable license for your project and then add it to your repository.

2.4. Repository CODE_OF_CONDUCT File

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.

Examples:

1. nodejs/admin
2. themerdev/themer
3. sourcerer-io/sourcerer-app

2.5. Repository CODEOWNERS File

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.

Examples:

1. dotnet/samples
2. GoogleCloudPlatform/python-docs-samples

Tools:

1. CODEOWNERS file syntax

2.6. Repository CITATION File

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.

Examples:

1. citation-file-format/citation-file-format
2. mhucka/readmine

Tools:

1. bibify Generator
2. zoterobib Generator
3. Generator of citation metadata files

2.7. Repository Description and Social Image

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.

Examples:

1. amplication/amplication
2. dbt-labs/dbt-core

2.8. Shields and Badges

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.

Examples:

1. MananTank/radioactive-state
2. create-go-app/cli

Tools:

1. Look in shields.io for a variety of pre-existing badges and the option to create custom ones.

Step 3: Automation/Checks

3.1. Automated Checks

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.

3.2. Building and Testing

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.

Tools:

1. CircleCI
2. Travis CI
3. Uffizzi Cloud
4. Apollo Studio

3.3. Code Style and Linting

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.

Tools:

1. Look here for the best code linter.

3.4. Utilising Kanban Board

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.

Tools:

1. Zenhub
2. Azure Boards
3. ClickUp
4. Asana
5. Zube

3.5. Branching Strategy

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.

Step 4: Advanced Options

4.1. GitHub Codespaces Configuration

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.

4.2. Issues Template Configuration

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.

Tools:

1. Issue template configuration

4.3. PRs Template Configuration

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.

Tools:

1. PR template configuration

4.4. Use Labels

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.

Step 5: Security

5.1. SECURITY File and Security Vulnerabilities

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!

Examples:

1. dotnet/samples
2. badges/shields

5.2. Role Defining

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.

5.3. Secrets Management

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.

1. GitGuardian
2. Aikido Security
3. Doppler
4. HashiCorp Vault
5. AWS Secrets Manager

5.4. Security Scanning

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.

PART II. OS Project Development

Step 1: Sponsor Acquisition

1.1. Sponsors Activation

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.

1.2. Monetization

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.

Step 2: Sponsor Acquisition

2.1. Contributors Onboarding

You have a full package of important info such as README, contributor guide, code of conduct guide, etc (mentioned in this checklist above).

2.2. Contributors Engagement

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.

Tools:

1. devActivity

2.3. Automating Greetings

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.

Step 3: Community Management

3.1. Community Support

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.

Examples:

1. kubernetes/kubernetes
2. Azure/data-api-builde
3. ProteGO-Safe/backend

3.2. Community Engagement

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.

3.3. 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.

Examples:

1. reactwg/react-18 - Using the Discussions board as a place to ask questions, propose changes, engage in deep-dive discussions, and announce new feature improvements, as well as beta and GA releases.
2. dogecoin/dogecoin - It is used for fielding feature requests from contributors, looking for developers willing to step up as contributors, and rooting out bad actors abusing its underlying blockchain technology, among other things.
3. nasa/cFS - NASA uses discussions to answer questions, share information, and collaborate with the open-source community on its core flight systems.
4. vercel/next.js - Space for conversations about work, planning, and community interaction, providing a platform for addressing issues and enhancing the community.

3.4. Promotion

Promote the project among those who are interested in it: new contributors, customers, partners:

• Share your project on social media platforms (Twitter, LinkedIn, Quora, Reddit, etc). Make sure to use relevant hashtags and engage with potential users.
• Submit your project to Pitchwall and Producthunt.
• Write a blog post, create a video tutorial about your project, and publish it on your website or platforms like Medium or YouTube.
• Participate in relevant online communities, such as forums, chat rooms, or discussion boards, and share your project with the community.
• Collaborate with other developers or open-source projects to increase your project's visibility and reach.

Conclusion

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.