diff --git a/.github/ISSUE_TEMPLATE/BUG_REPORT.md b/.github/ISSUE_TEMPLATE/BUG_REPORT.md new file mode 100644 index 0000000..8eaadea --- /dev/null +++ b/.github/ISSUE_TEMPLATE/BUG_REPORT.md @@ -0,0 +1,36 @@ +--- +name: Bug Report +about: Report a bug to help us improve +title: '' +labels: '' +assignees: '' + +--- + +## Description + +Please provide a description of the problem. + +## Expected Behavior + +Please describe what you expected would happen. + +## Actual Behavior + +Please describe what happened instead. + +## Affected Version + +Please provide the version number where this issue was encountered. + +## Steps to Reproduce + +1. First step +1. Second step +1. etc. + +## Checklist + + +- [ ] I have read the [contributing guidelines](/CONTRIBUTING.md) +- [ ] I have verified this does not duplicate an existing issue diff --git a/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md b/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md new file mode 100644 index 0000000..2af6aba --- /dev/null +++ b/.github/ISSUE_TEMPLATE/FEATURE_REQUEST.md @@ -0,0 +1,25 @@ +--- +name: Feature Request +about: Suggest a feature for this project +title: '' +labels: '' +assignees: '' + +--- + +## Problem Statement + +Please describe the problem to be addressed by the proposed feature. + +## Proposed Solution + +Please describe what you envision the solution to this problem would look like. + +## Alternatives Considered + +Please briefly describe which alternatives, if any, have been considered, including merits of alternate approaches and +tradeoffs being made. + +## Additional Context + +Please provide any other information that may be relevant. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..d9670b4 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,27 @@ +## Description + +Please provide a meaningful description of what this change will do, or is for. Bonus points for including links to +related issues, other PRs, or technical references. + +Note that by _not_ including a description, you are asking reviewers to do extra work to understand the context of this +change, which may lead to your PR taking much longer to review, or result in it not being reviewed at all. + +## Type of Change + +- [ ] Bug Fix +- [ ] New Feature +- [ ] Breaking Change +- [ ] Refactor +- [ ] Documentation +- [ ] Other (please describe) + +## Checklist + + +- [ ] I have read the [contributing guidelines](/CONTRIBUTING.md) +- [ ] Existing issues have been referenced (where applicable) +- [ ] I have verified this change is not present in other open pull requests +- [ ] Functionality is documented +- [ ] All code style checks pass +- [ ] New code contribution is covered by automated tests +- [ ] All new and existing tests pass diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..8d85f88 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,11 @@ +version: 2 +updates: + - package-ecosystem: "github-actions" + directory: "/" + groups: + github: + patterns: + - "actions/*" + - "github/*" + schedule: + interval: "weekly" diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml new file mode 100644 index 0000000..bdee019 --- /dev/null +++ b/.github/workflows/lint.yml @@ -0,0 +1,24 @@ +name: lint + +on: + push: + branches: + # Run on pushes to default branch + - main + # Run against pull requests + pull_request: + +jobs: + markdown: + runs-on: ubuntu-latest + steps: + - name: 🔒 harden runner + uses: step-security/harden-runner@63c24ba6bd7ba022e95695ff85de572c04a18142 # v2.7.0 + with: + egress-policy: audit + - uses: actions/checkout@9bb56186c3b09b4f86b1c65136769dd318469633 # v4.1.2 + - name: ⬇️ lint markdown files + uses: avto-dev/markdown-lint@04d43ee9191307b50935a753da3b775ab695eceb # v1.5.0 + with: + config: ".markdownlint.json" + args: "**/*.md .github/**/*.md" diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml new file mode 100644 index 0000000..532cc5c --- /dev/null +++ b/.github/workflows/scorecard.yml @@ -0,0 +1,29 @@ +name: scorecard + +on: + push: + branches: + # Run on pushes to default branch + - main + schedule: + # Run weekly on Saturdays + - cron: "30 1 * * 6" + # Run when branch protection rules change + branch_protection_rule: + # Run the workflow manually + workflow_dispatch: + +# Declare default permissions as read-only +permissions: read-all + +jobs: + run-scorecard: + # Call reusable workflow file + uses: cisco-ospo/.github/.github/workflows/_scorecard.yml@main + permissions: + id-token: write + security-events: write + secrets: inherit + with: + # Publish results of Scorecard analysis + publish-results: true diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml new file mode 100644 index 0000000..152ddf8 --- /dev/null +++ b/.github/workflows/stale.yml @@ -0,0 +1,25 @@ +name: stale + +on: + schedule: + # Run weekly on Saturdays + - cron: "30 1 * * 6" + # Run the workflow manually + workflow_dispatch: + +# Declare default permissions as read-only +permissions: read-all + +jobs: + mark-stale: + # Call reusable workflow file + uses: cisco-ospo/.github/.github/workflows/_stale.yml@main + permissions: + contents: read + issues: write + pull-requests: write + with: + days-until-stale: 60 + days-until-close: 7 + stale-label: "stale" + exempt-label: "keep" diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000..2a820e7 --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,16 @@ +{ + "default": true, + "MD013": { + "line_length": 10000, + "headings": false, + "code_blocks": false, + "tables": false + }, + "MD024": { + "siblings_only": true + }, + "MD025": { + "front_matter_title": "" + }, + "MD041": false +} diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..d0925d6 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,24 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### TBA + +## [1.0.0] - 2024-02-16 + +### Added + +- Add initial workflow for calling reusable workflow by @lelia in #3 +- README: Fix maintainer reference by @GaryPWhite in #1 +- .github: Add Scorecard workflow by @lelia in #10 +- .github: Add Dependabot configuration by @openclarity-service in #11 +- Deprecate Renovate and fix GitHub URL refs by @lelia in #14 +- Bump actions/checkout from 3.6.0 to 4.1.1 by @dependabot in #15 + +[unreleased]: https://github.com/cisco-ospo/oss-template/compare/v1.0.0...HEAD +[1.0.0]: https://github.com/cisco-ospo/oss-template/releases/tag/v1.0.0 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..4b161db --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,132 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual identity +and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or + advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official email address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +**. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series +of actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within +the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available +at [https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..7bd83d5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,47 @@ +# How to Contribute + +Thanks for your interest in contributing to ``! Here are a few general guidelines on contributing and +reporting bugs that we ask you to review. Following these guidelines helps to communicate that you respect the time of +the contributors managing and developing this open source project. In return, they should reciprocate that respect in +addressing your issue, assessing changes, and helping you finalize your pull requests. In that spirit of mutual respect, +we endeavor to review incoming issues and pull requests within 10 days, and will close any lingering issues or pull +requests after 60 days of inactivity. + +Please note that all of your interactions in the project are subject to our [Code of Conduct](/CODE_OF_CONDUCT.md). This +includes creation of issues or pull requests, commenting on issues or pull requests, and extends to all interactions in +any real-time space e.g., Slack, Discord, etc. + +## Reporting Issues + +Before reporting a new issue, please ensure that the issue was not already reported or fixed by searching through our +[issues list](https://github.com/org_name/repo_name/issues). + +When creating a new issue, please be sure to include a **title and clear description**, as much relevant information as +possible, and, if possible, a test case. + +**If you discover a security bug, please do not report it through GitHub. Instead, please see security procedures in +[SECURITY.md](/SECURITY.md).** + +## Sending Pull Requests + +Before sending a new pull request, take a look at existing pull requests and issues to see if the proposed change or fix +has been discussed in the past, or if the change was already implemented but not yet released. + +We expect new pull requests to include tests for any affected behavior, and, as we follow semantic versioning, we may +reserve breaking changes until the next major version release. + +## Other Ways to Contribute + +We welcome anyone that wants to contribute to `` to triage and reply to open issues to help troubleshoot +and fix existing bugs. Here is what you can do: + +- Help ensure that existing issues follows the recommendations from the _[Reporting Issues](#reporting-issues)_ section, + providing feedback to the issue's author on what might be missing. +- Review and update the existing content of our [Wiki](https://github.com/org_name/repo_name/wiki) with up-to-date + instructions and code samples. +- Review existing pull requests, and testing patches against real existing applications that use ``. +- Write a test, or add a missing test case to an existing test. + +Thanks again for your interest on contributing to ``! + +:heart: diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 0000000..422fdc0 --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,5 @@ +# Maintainers + +- [GitHub Username](https://github.com/username) +- [GitHub Username](https://github.com/username) +- [GitHub Username](https://github.com/username) diff --git a/README.md b/README.md new file mode 100644 index 0000000..bf70fd1 --- /dev/null +++ b/README.md @@ -0,0 +1,95 @@ +# Open Source Project Template + +[![Release](https://img.shields.io/github/v/release/cisco-ospo/oss-template?display_name=tag)](CHANGELOG.md) +[![Lint](https://github.com/cisco-ospo/oss-template/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/cisco-ospo/oss-template/actions/workflows/lint.yml) +[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-fbab2c.svg)](CODE_OF_CONDUCT.md) +[![Maintainer](https://img.shields.io/badge/Maintainer-Cisco-00bceb.svg)](https://opensource.cisco.com) + +## Before You Start + +As much as possible, we have tried to provide enough tooling to get you up and running quickly and with a minimum of effort. This includes sane defaults for documentation; templates for bug reports, feature requests, and pull requests; and [GitHub Actions](https://github.com/features/actions) that will automatically manage stale issues and pull requests. This latter defaults to labeling issues and pull requests as stale after 60 days of inactivity, and closing them after 7 additional days of inactivity. These [defaults](.github/workflows/stale.yml) and more can be configured. For configuration options, please consult the documentation for the [stale action](https://github.com/actions/stale). + +In trying to keep this template as generic and reusable as possible, there are some things that were omitted out of necessity and others that need a little tweaking. Before you begin developing in earnest, there are a few changes that need to be made: + +- [ ] ✅ Select an appropriate license for your project. This can easily be achieved through the 'Add File' button on the GitHub UI, naming the file `LICENSE`, and selecting your desired license from the provided list. +- [ ] Update the `` placeholder in this file to reflect the name of the license you selected above. +- [ ] Replace `[INSERT CONTACT METHOD]` in [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) with a suitable communication channel. +- [ ] Change references to `org_name` to the name of the org your repo belongs to (eg. `cisco-open`): + - [ ] In [`README.md`](README.md) + - [ ] In [`CONTRIBUTING.md`](CONTRIBUTING.md) +- [ ] Change references to `repo_name` to the name of your new repo: + - [ ] In [`README.md`](README.md) + - [ ] In [`CONTRIBUTING.md`](CONTRIBUTING.md) +- [ ] Update the link to the contribution guidelines to point to your project: + - [ ] In [`.github/ISSUE_TEMPLATE/BUG_REPORT.md`](.github/ISSUE_TEMPLATE/BUG_REPORT.md) + - [ ] In [`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md) +- [ ] Replace the `` placeholder with the name of your project: + - [ ] In [`CONTRIBUTING.md`](CONTRIBUTING.md) + - [ ] In [`SECURITY.md`](SECURITY.md) +- [ ] Add names and contact information for actual project maintainers to [`MAINTAINERS.md`](MAINTAINERS.md). +- [ ] Delete the content of [`CHANGELOG.md`](CHANGELOG.md). We encourage you to [keep a changelog](https://keepachangelog.com/en/1.0.0/). +- [ ] Configure [`.github/dependabot.yaml`](dependabot.yaml) for your project's language and tooling dependencies. +- [ ] Replace the generic content in this file with the relevant details about your project. +- [ ] Acknowledge that some features like [branch protection rules](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/managing-a-branch-protection-rule) are only available when the repo is `public`. +- [ ] 🚨 Delete this section of the `README`! + +## About The Project + +Provide some information about what the project is/does. + +## Getting Started + +To get a local copy up and running follow these simple steps. + +### Prerequisites + +This is an example of how to list things you need to use the software and how to install them. + +- npm + + ```sh + npm install npm@latest -g + ``` + +### Installation + +1. Clone the repo + + ```sh + git clone https://github.com/org_name/repo_name.git + ``` + +2. Install NPM packages + + ```sh + npm install + ``` + +## Usage + +Use this space to show useful examples of how a project can be used. Additional screenshots, code examples and demos work well in this space. You may also link to more resources. + +_For more examples, please refer to the [Documentation](https://example.com) or the [Wiki](https://github.com/org_name/repo_name/wiki)_ + +## Roadmap + +See the [open issues](https://github.com/org_name/repo_name/issues) for a list of proposed features (and known issues). + +## Contributing + +Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. For detailed contributing guidelines, please see [CONTRIBUTING.md](CONTRIBUTING.md) + +## License + +Distributed under the `` License. See [LICENSE](LICENSE) for more information. + +## Contact + +Your Name - [@twitter_handle](https://twitter.com/twitter_handle) - email + +Project Link: [https://github.com/org_name/repo_name](https://github.com/org_name/repo_name) + +## Acknowledgements + +This template was adapted from +[https://github.com/othneildrew/Best-README-Template](https://github.com/othneildrew/Best-README-Template). diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..210a9c1 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,39 @@ +# Security Policies and Procedures + +This document outlines security procedures and general policies for the +`` project. + +- [Reporting a Bug](#reporting-a-bug) +- [Disclosure Policy](#disclosure-policy) +- [Comments on this Policy](#comments-on-this-policy) + +## Reporting a Bug + +The `` team and community take all security bugs in +`` seriously. Thank you for improving the security of +``. We appreciate your efforts and responsible disclosure and +will make every effort to acknowledge your contributions. + +Report security bugs by emailing `oss-security@cisco.com`. + +The lead maintainer will acknowledge your email within 48 hours, and will send a +more detailed response within 48 hours indicating the next steps in handling +your report. After the initial reply to your report, the security team will +endeavor to keep you informed of the progress towards a fix and full +announcement, and may ask for additional information or guidance. + +## Disclosure Policy + +When the security team receives a security bug report, they will assign it to a +primary handler. This person will coordinate the fix and release process, +involving the following steps: + +- Confirm the problem and determine the affected versions. +- Audit code to find any potential similar problems. +- Prepare fixes for all releases still under maintenance. These fixes will be + released as quickly as possible. + +## Comments on this Policy + +If you have suggestions on how this process could be improved please submit a +pull request.