Skip to content

Checklist for publishing a new OS project

Christopher Jennings edited this page Mar 20, 2019 · 16 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.

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:

  • respond to issues
  • review, test, and merge pull requests (PR must not be left without a response longer than a day)
  • take care of CI
  • release new versions, etc.

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

In 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

License

Use the MIT license. If you want to use a different license, please contact the community team.

Issue & pull request templates & Code of Conduct

Use https://github.com/Kentico/oss-automation to automate creation of the templates.

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:

Google Analytics

Add Google Analytics Beacon service to the bottom of README. The format is the following:

![Analytics](https://kentico-ga-beacon.azurewebsites.net/api/UA-[account property ID]/[relative page path]?pixel)

Example:

![Analytics](https://kentico-ga-beacon.azurewebsites.net/api/UA-69014260-4/Kentico/delivery-sdk-net/wiki/Home?pixel)

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

  • Set up a build agent (AppVeyor, Travis, etc.)
    • Make it run tests
    • Fail builds on failed tests
  • Set up status checks via web hooks

Protect the master branch

Status checks

Add collaborating teams

  • 🔒 Required for private repositories too Collaborators

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

Releases

Want to make the repo even more friendly?

Analytics

You can’t perform that action at this time.