Skip to content

Checklist for publishing a new OS project

Ondřej Chrastina edited this page Nov 18, 2021 · 38 revisions

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

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 Green community profile

Description, website, and topics

  • 🔒 Required for private repositories too

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

⚠ 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).

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 "Kentico" 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 in the root of the repository because it is being linked from "CONTRIBUTING.md" document.

Issue & pull request templates & Code of Conduct

Use repo-template for the templates and Code of Conduct.

GitHub features

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

GH Features

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 Kentico'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/ Custom Badge

Examples:

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.

Protect the master branch

You can learn more about branch protection in the documentation. Branch protection

Add collaborating teams

  • 🔒 Required for private repositories too Collaborators

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

Releases

Want to make the repo even more friendly?