Checklist for publishing a new OS project

Before you publish any repository under Kontent.ai organization on GitHub, please go through this checklist and make sure the repository is up to standards.

• Repository name
• Dedicate a maintainer🔒
• Fulfill Community profile🔒
• Set up GitHub features🔒
• Set Expectations🔒
• Add badges
• Add automatic tests❔
• Set up Continuous Integration❔
• Protect Master Branch
• Add collaborating teams🔒
• Define release process

Repository name

Set repository name according to the Naming conventions.

Dedicate a maintainer

• 🔒 Required for private repositories too

It's essential to decide who's going to be responsible for the repository. Every repository needs to have an owner (a person or a team) who will actively:

• set the right expectations about the project
• keep the repository in a good shape

Read more on the duties of a maintainer.

Mark this user into the CODEOWNERS file. See an example.

Community profile

• should be "all green"
• please note that it's available only for public repos and not for forked repos

Description, website, and topics

• 🔒 Required for private repositories too

Fill in basic information about the project to make it easy to find it.

⚠ Tag the repository based on the division according to Naming conventions.

In the case of private repositories, add a "private-repository" tag.

README (Documentation)

• 🔒 Required for private repositories too

README should contain:

• installation instructions
• basic demonstration of usage
• code examples (if applicable)

More complex topics and examples can be covered in separate articles in GitHub Wiki (or an external system such as ReadTheDocs).

The template of the README file is stored in special ".github" repository.

Contributing

From the README or CONTRIBUTING files, it should be clear:

• how to set up the project in order to contribute
  • this may include creating a PowerShell or other (e.g. build) script to make it easy for the contributors
• what kind of contributions are accepted and welcome
• what's the definition of done (use PR templates)
• which communication channels should be used to get in touch with the maintainer

The template of CONTRIBUTING file is stored in repo-template.

License

Use the MIT license and set "Kontent.ai" as the copyright holder. If you want to use a different license, please contact the DevRel team.

Store the license in the "LICENSE.md" file.

The template of the LICENSE file is stored in special ".github" repository.

Issue & pull request templates & Code of Conduct

Automatically used from special ".github" repository, see the docs for more details.

Security policy

Automatically used from special ".github" repository, see the docs for more details.

GitHub features

• 🔒 Required for private repositories too Decide which features you turn on or off. This will help set expectations.

Expectations

• 🔒 Required for private repositories too

You should make clear:

• what kind of support users can expect (README)
  • GH issues vs. StackOverflow, etc.
• how to submit bugs (README + Issue/PR templates)
• what the future of the project is and whether it's actively developed (set up a project/backlog or archive a repo that's no longer being developed)

In case of private repos, please add the following note to the top of the README:

🛈 This repository contains Kontent.ai's internal code that is of no use to the general public. Please explore our other repositories.

Set up an issue tracker. Most likely, you'll use GitHub issues. Take your time to set up labels and milestones.

Badges

Use badges to make it easy to find basic information about the status of the project.

Pro tip: generate custom badges via https://shields.io/

Examples:

• Continuous Integration
  • 
• Test coverage
  • Code Climate
• Static code analysis result
  • Code Climate
  • SonarCloud
• Deployment/Package status
  • Netlify
  • npm
  • nuget
• Chat
  • Stack Overflow
  • Discord ()

⚠ Try to unify the style of the badge statuses. If it is not possible group the stypes per line.

Tests

• ❔ Optional, but highly recommended.

Include at least a basic set of (unit) tests.

Review

• Ask your colleagues to do a code review, basic testing, and proofreading before you publish any project. The DevRel team may also help.

Continuous Integration

• ❔ Optional, but highly recommended.

Setting up CI, makes it easy for contributors to know whether their code works as expected. You can find more info about CI practices in the separate article.

• Set up a build agent - GitHub Actions
  • Make it run tests
  • Fail builds on failed tests
• Set up status checks via webhooks

Protect the master branch

You can learn more about branch protection in the documentation.

Add collaborating teams

• 🔒 Required for private repositories too

In most cases, it'll be Admin permission for the Developer Relations team and Write permission for the Employees team.

Releases

• Create an initial release
• Always follow Semantic Versioning

Want to make the repo even more friendly?

• Read the Pre-launch checklist.