Skip to main content
As an inner-source ecosystem grows, the number of repositories can make it difficult for teams to discover the right code, documentation, or services. To prevent information silos and improve reuse, projects should be proactively organized and documented so others across the organization can locate, evaluate, and contribute to them. This guide summarizes the core standards that make an internal repository discoverable, easy to adopt, and simple to maintain.

​
1. Descriptive repository naming

Choose functional, meaningful repository names that reflect the project’s purpose and domain. Avoid vague or internal-only code names that provide no context to new readers. Table: naming examples A clear name helps users infer the repository scope when browsing search results, dashboards, or internal catalogs.

​
2. Concise summary (one- or two-sentence description)

Add a short, one- or two-sentence description at the top of the repository so potential users can quickly decide whether the project fits their needs. This summary should appear in the README header and in the repository description field (if your platform supports it). Example README header snippet:
Place the summary prominently and keep it focused on what the project does, who should use it, and the primary problem it solves.

​
3. Clear licensing

Always include a LICENSE file in the repository root. Even for internal projects, an explicit license clarifies how code may be used, modified, and redistributed inside your organization and supports legal and security reviews.
Including a LICENSE file prevents confusion about reuse and speeds up legal and security reviews. If your organization uses a standard internal license template, include that exact file and note any third-party license requirements.
Example LICENSE header for an internal project:
If third-party libraries are used, also include a THIRD_PARTY_NOTICES or NOTICE file that lists those components and attribution text.
Do not omit license information. Missing or ambiguous licensing is a common blocker for reuse and dependency approvals.

​
4. Standardized landing page (README.md)

Maintain a README.md in the repository root. Many platforms render this file as the repository’s front door, so use it to set expectations and streamline onboarding. A discoverable README should include:
  • A short one-line description (# Project Name + one sentence).
  • Quick-start instructions so developers can run or use the project locally.
  • Usage examples and common workflows.
  • Links to architecture docs, API reference, and design docs.
  • Contribution guidance or a pointer to CONTRIBUTING.md.
  • Maintainer or team contact information.
Minimal, discoverable README structure:
Table: README section examples

​
Additional practices that improve discoverability

  • Add repository topics/tags (e.g., payments, frontend, go, microservice) to improve search and filtering.
  • Provide a clear directory structure and a top-level documentation folder (for example, /docs or /architecture) for deeper design and architecture information.
  • Include CONTRIBUTING.md and CODE_OF_CONDUCT.md to lower barriers for new contributors and set expectations for collaboration.
  • Maintain CHANGELOG.md or release notes so readers can quickly see what changed and when.
  • Use issue templates and labels so reported problems are easier to triage, filter, and find.
  • Expose a single source of truth for dependencies and build tooling (package.json, go.mod, requirements.txt, or similar).
  • Consider adding a short “status” badge (build, coverage, latest release) near the top of the README to surface project health.
By applying these core standards—descriptive naming, concise summaries, clear licensing, and a standardized landing page—along with the additional best practices above, repositories become far easier to find, understand, and contribute to across your organization.

Watch Video