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.

💡 Starting a new repository? Create it from our repo-template (hit Use this template on GitHub). It comes pre-loaded with the LICENSE, a README template, CONTRIBUTING and CODE_OF_CONDUCT files, a SECURITY policy, and issue/PR templates - covering a large part of this checklist out of the box.

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 s.r.o." 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 surface key project status at a glance - you can generate custom ones with shields.io. Useful badges include:

⚠ Keep the badge styles consistent - if you can't, at least group them 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. We recommend GitHub Actions:

  • build and run tests on every push and pull request
  • fail the build when tests fail
  • enforce status checks before merging

AI agent context (CLAUDE.md)

  • ❔ Optional, but recommended for larger repositories or those with significant expected developer traffic.

Repositories with a non-trivial codebase or active contribution should include a curated CLAUDE.md file in the repository root. It gives AI coding agents (and new human contributors) a fast, accurate overview of the project so they can be productive without reverse-engineering the whole codebase.

A good CLAUDE.md is concise and curated - not auto-generated boilerplate - and typically covers:

  • Purpose - what the repository is and what problem it solves
  • Architecture overview - the main projects/packages/modules and how they fit together
  • Common commands - how to build, test, lint, and run the project locally (including non-obvious flags used in CI)
  • Key patterns & conventions - architectural patterns, code-style rules, and project-specific idioms an agent should follow
  • Gotchas - anything surprising: required environment variables, services needed for integration tests, generated code, etc.

Keep it in sync with the codebase as the project evolves - an outdated CLAUDE.md is worse than none. For examples, see the CLAUDE.md files in management-sdk-net (.NET) or rich-text-resolver-js (JS/TS).

The file is named CLAUDE.md for Claude Code; the emerging tool-agnostic equivalent is AGENTS.md. You can maintain one and symlink the other if you want to support multiple agents from a single source of truth.

Protect the master branch

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

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

Want to make the repo even more friendly?