/template-repository

Best practices for creating repository.

Apache License 2.0Apache-2.0

template-repository

If you are beginning your journey with Senzing, please start with Senzing Quick Start guides.

You are in the Senzing Garage where projects are "tinkered" on. Although this GitHub repository may help you understand an approach to using Senzing, it's not considered to be "production ready" and is not considered to be part of the Senzing product. Heck, it may not even be appropriate for your application of Senzing!

This repository contains exemplar artifacts (files) for Senzing repositories.

GitHub provides support for these artifacts. As an example, click on the following links on this GitHub repository:

  • "Insights" tab > "Community" on left-hand navigation bar

Files

Senzing community files:

  1. CHANGELOG.md
  2. CODE_OF_CONDUCT.md
  3. CONTRIBUTING.md
  4. docs/
  5. .github/
    1. CODEOWNERS
    2. dependabot.yml
    3. senzing-corporate-contributor-license-agreement.pdf
    4. senzing-individual-contributor-license-agreement.pdf
    5. workflows/
  6. LICENSE
  7. README.md

README.md

Although the file you are reading is a README.md file, this isn't the style of README.md for most projects. Depending upon the type of repository, the following README.md templates may be more appropriate:

  1. README.md template for demonstrations. Examples:
    1. template-docker/README.md
    2. template-go/README.md
    3. template-python/README.md

CHANGELOG.md

The contents of CHANGELOG.md are meant to be consumed by users of the repository. As such, they need to know what changes affect them as users. In general, changes that do not effect users should not be captured in CHANGELOG.md. For this reason, automatic generation of CHANGELOG.md entries is discouraged.

The format of CHANGELOG.md is based on Keep a Changelog, markdownlint. Also, projects adhere to Semantic Versioning.

CODE_OF_CONDUCT.md

The CODE_OF_CONDUCT.md file describes the social conventions among contributors to the repository.

A code of conduct defines standards for how to engage in a community. It signals an inclusive environment that respects all contributions. It also outlines procedures for addressing problems between members of your project's community. For more information on why a code of conduct defines standards and expectations for how to engage in a community, see the Open Source Guide.

-- GitHub's Adding a code of conduct to your project

The CODE_OF_CONDUCT.md file in this repository is based on GitHub's "Contributor Covenant".

How to create CODE_OF_CONDUCT.md

  1. Option #1: Using GitHub's "Wizard"
    1. github.com > (choose repository) > Insights > Community > Code of conduct > "Add" button > "Contributor Covenant"
  2. Option #2: Manual file creation
    1. See GitHub's Adding a code of conduct to your project
    2. Alternative CODE_OF_CONDUCT.md content:
      1. Apache Software Foundation Code of Conduct

CONTRIBUTING.md

The CONTRIBUTING.md file describes the process for contributing to the repository.

To help your project contributors do good work, you can add a file with contribution guidelines to your project repository's root. When someone opens a pull request or creates an issue, they will see a link to that file.

-- GitHub's Setting guidelines for repository contributors

The CONTRIBUTING.md file in this repository is an example that needs to be modified to represent the requirements of the actual repository.

How to create CONTRIBUTING.md

  1. Option #1: Using GitHub's "Wizard"
    1. github.com > (choose repository) > Insights > Community > Contributing > "Add" button
  2. Option #2: Manual file creation
    1. See GitHub's Setting guidelines for repository contributors

docs

The docs/ subdirectory may be published as GitHub Pages. They become visible at hub.senzing.com. URLs have the format:

https://hub.senzing.com/<repository-name>

Example: hub.senzing.com/sdk-components-ng

.github

.github/CODEOWNERS

The CODEOWNERS file implements GitHub's code owners. The teams that may appear in a CODEOWNERS file can be seen at github.com/orgs/Senzing/teams.

.github/dependabot.yml

The dependabot.yml file is configuration for GitHub's dependabot.

.github/senzing-corporate-contributor-license-agreement.pdf

The Senzing, INC. Software Grant and Corporate Contributor License Agreement (CCLA), corporate-contributor-license-agreement.pdf, is the standard agreement for a corporation's contribution to a Senzing repository.

How to create .github/senzing-corporate-contributor-license-agreement.pdf

  1. Make a .github directory in the repository
  2. Copy senzing-corporate-contributor-license-agreement.pdf into the new .github directory
  3. DO NOT modify the contents of senzing-corporate-contributor-license-agreement.pdf without legal approval.
  4. Reference senzing-corporate-contributor-license-agreement.pdf in CONTRIBUTING.md

.github/senzing-individual-contributor-license-agreement.pdf

The Individual Contributor License Agreement (ICLA), senzing-individual-contributor-license-agreement.pdf, is the standard agreement for an individual's contribution to a Senzing repository. Note: if an individual is contributing on behalf of a company, the senzing-corporate-contributor-license-agreement.pdf must also be submitted and accepted.

How to create .github/senzing-individual-contributor-license-agreement.pdf

  1. Make a .github directory in the repository
  2. Copy senzing-individual-contributor-license-agreement.pdf into the new .github directory
  3. DO NOT modify the contents of senzing-individual-contributor-license-agreement.pdf without legal approval.
  4. Reference senzing-individual-contributor-license-agreement.pdf in CONTRIBUTING.md

.github/workflows

LICENSE

The LICENSE file describes the terms and conditions under which the code in the repository can be used. The recommended license file is "Apache License 2.0". A comparison of licenses can be found at choosealicense.com.

The LICENSE file in this repository is based on "Apache License 2.0".

How to create LICENSE

  1. Option #1: Using GitHub's "Wizard"
    1. When creating a new repository, in the "Add a license:" drop-down, choose "Apache License 2.0"
  2. Option #2: Manual file creation
    1. See GitHub's Adding a license to a repository