diff --git a/.agents/bin/setup b/.agents/bin/setup new file mode 100755 index 0000000..fca95e5 --- /dev/null +++ b/.agents/bin/setup @@ -0,0 +1,29 @@ +#!/bin/sh +set -eu + +root="$(CDPATH= cd -- "$(dirname -- "$0")/../.." && pwd)" +tool_bin="$root/.agents/.tools/bin" +actionlint_version="1.7.12" + +if ! command -v ruby >/dev/null 2>&1; then + echo "Ruby is required to validate the repository YAML." >&2 + exit 1 +fi + +installed_version="" +if [ -x "$tool_bin/actionlint" ]; then + installed_version="$("$tool_bin/actionlint" -version 2>/dev/null | sed -n '1p' || true)" +fi + +if [ "$installed_version" = "$actionlint_version" ]; then + exit 0 +fi + +if ! command -v go >/dev/null 2>&1; then + echo "Go is required to install the pinned actionlint validator." >&2 + echo "Install Go, then rerun .agents/bin/setup." >&2 + exit 1 +fi + +mkdir -p "$tool_bin" +GOBIN="$tool_bin" go install "github.com/rhysd/actionlint/cmd/actionlint@v$actionlint_version" diff --git a/.agents/bin/validate b/.agents/bin/validate new file mode 100755 index 0000000..7751524 --- /dev/null +++ b/.agents/bin/validate @@ -0,0 +1,43 @@ +#!/bin/sh +set -eu + +root="$(CDPATH= cd -- "$(dirname -- "$0")/../.." && pwd)" +PATH="$root/.agents/.tools/bin:$PATH" +export PATH +cd "$root" + +ruby -e ' + require "yaml" + Dir[".github/**/*.yml", ".github/**/*.yaml"].sort.each do |file| + YAML.safe_load_file(file, aliases: true) + end +' + +if ! command -v actionlint >/dev/null 2>&1; then + echo "actionlint is required to validate GitHub Actions workflows" >&2 + exit 1 +fi + +if [ "$(actionlint -version 2>/dev/null | sed -n '1p')" != "1.7.12" ]; then + echo "actionlint 1.7.12 is required; run .agents/bin/setup" >&2 + exit 1 +fi + +actionlint + +git diff --check +git diff --cached --check + +ruby -e ' + files = `git ls-files --others --exclude-standard -z`.split("\0") + errors = files.flat_map do |file| + data = File.binread(file) + next [] if data.include?("\0") + + data.lines.each_with_index.filter_map do |line, index| + content = line.sub(/\r?\n\z/, "") + "#{file}:#{index + 1}: trailing whitespace" if content.match?(/[ \t]+\z/) + end + end + abort(errors.join("\n")) unless errors.empty? +' diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..6ccb3e1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,44 @@ +name: Bug report +description: Report reproducible incorrect behavior +title: "[Bug]: " +body: + - type: markdown + attributes: + value: | + Thanks for reporting a bug. Do not include secrets, private data, or vulnerability details. + - type: textarea + id: summary + attributes: + label: Summary + description: What happened, and what did you expect? + validations: + required: true + - type: textarea + id: reproduction + attributes: + label: Minimal reproduction + description: Link to or describe the smallest complete reproduction and exact steps. + validations: + required: true + - type: textarea + id: versions + attributes: + label: Versions and environment + description: Project, language/runtime, framework, package manager, operating system, and browser versions as applicable. + validations: + required: true + - type: textarea + id: evidence + attributes: + label: Logs or additional evidence + description: Paste relevant sanitized logs, stack traces, screenshots, or recordings. + render: shell + - type: checkboxes + id: checks + attributes: + label: Preflight + options: + - label: I searched existing issues and discussions. + required: true + - label: This is not a security vulnerability. + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..34e23df --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Security vulnerability + url: https://github.com/shakacode/.github/security/policy + about: Read the private reporting instructions before sharing vulnerability details. + - name: Commercial support + url: https://www.shakacode.com + about: Contact ShakaCode for consulting and commercial support. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..c39ac7d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,37 @@ +name: Feature request +description: Propose a focused improvement +title: "[Feature]: " +body: + - type: textarea + id: problem + attributes: + label: Problem and users + description: Who needs this, and what can they not do today? + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed solution + description: Describe the behavior, public API, and important tradeoffs. + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Existing workarounds or smaller options you evaluated. + - type: textarea + id: maintenance + attributes: + label: Maintenance impact + description: Compatibility, dependencies, documentation, testing, support, and migration implications. + - type: checkboxes + id: checks + attributes: + label: Preflight + options: + - label: I searched existing issues and discussions. + required: true + - label: I am willing to help implement or validate this proposal. + required: false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..ac7ea8e --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,25 @@ +## Why + + + +## What changed + + + +## Validation + + + +- [ ] Focused tests added or updated, or not applicable with explanation +- [ ] Repository validation/CI run +- [ ] Documentation/changelog updated when behavior changed +- [ ] No secrets, private data, or incompatible licensed material included + +## Risk and rollout + + + +## Contributor declaration + +- [ ] I reviewed and understand every line in this change. +- [ ] I disclosed material AI assistance, if any, and independently verified its output. diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..9a350e5 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,7 @@ +version: 2 +updates: + - package-ecosystem: github-actions + directory: / + schedule: + interval: monthly + open-pull-requests-limit: 5 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..ef40ddc --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.agents/.tools/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..52bba78 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,17 @@ +# ShakaCode organization defaults + +This public repository supplies organization profile and community-health +defaults. Do not include private repository names, credentials, customer +information, or internal operational details. + +## Workflow + +- Base branch: `main` +- Setup: `.agents/bin/setup` (requires Ruby and Go; installs pinned + `actionlint` under `.agents/.tools/`) +- Validation: `.agents/bin/validate` +- Changes require a feature branch and pull request. +- Organization defaults must remain broadly applicable. Put project-specific + commands and policy in that project's repository. + +Review all workflow permission changes and external action references explicitly. diff --git a/AGENT_WORKFLOW_TEMPLATE.md b/AGENT_WORKFLOW_TEMPLATE.md new file mode 100644 index 0000000..37fe8e2 --- /dev/null +++ b/AGENT_WORKFLOW_TEMPLATE.md @@ -0,0 +1,35 @@ +# Agent workflow template + +Copy and adapt this into a repository's `AGENTS.md`. Replace every placeholder; +repository-specific instructions are more useful than generic prose. + +## Repository seam + +- Default branch: `` +- Setup: `` +- Validate: `` +- Tests: `` +- Lint/format: `` +- Build/package: `` + +## Safety boundaries + +- Credentials and external systems: `` +- Production/customer data: `` +- Destructive actions: `` +- Generated files: `` + +## Coordination + +- Shared service/environment: `` +- Worker identity and collision domain: `` +- Hosted example/deployment: `` + +## Completion gate + +1. Run ``. +2. Exercise changed behavior with ``. +3. Obtain independent review for non-trivial changes. +4. Commit to a feature branch and open a pull request. + +If Claude Code is used, add a `CLAUDE.md` containing `@AGENTS.md`. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..1768e78 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,28 @@ +# ShakaCode open-source code of conduct + +We want ShakaCode projects to be welcoming, technically rigorous places where +people can collaborate across backgrounds, identities, locations, and levels of +experience. + +## Expected behavior + +- Be respectful, specific, and constructive. +- Critique ideas and code, not people. +- Assume good intent while addressing concrete impact. +- Make room for questions and different experience levels. +- Respect privacy, attribution, licenses, and maintainer boundaries. +- Accept moderation decisions and step back when asked. + +Harassment, discrimination, threats, sexualized attention, doxxing, deliberate +disruption, and sustained personal attacks are not acceptable. + +## Reporting + +For ordinary project disagreements, contact the repository maintainers. For a +private conduct concern, email [contact@shakacode.com](mailto:contact@shakacode.com) +with the subject `Open-source conduct report`. Do not post sensitive evidence +publicly. Reports will be handled as privately as practical, with conflicts of +interest avoided where possible. + +Maintainers may edit or remove content, warn participants, temporarily restrict +participation, or permanently ban someone when needed to protect the community. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..7e69794 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,52 @@ +# Contributing to ShakaCode open source + +Thank you for helping improve a ShakaCode project. Repository-specific +instructions take precedence over this organization default. + +## Before starting + +- Search existing issues and pull requests. +- For a substantial feature, public API change, dependency migration, or broad + refactor, open an issue or discussion before investing significant work. +- Keep security reports private; follow the repository's security policy. +- Confirm the repository is actively maintained. An old repository may be kept + for historical or compatibility reasons. + +## A useful contribution + +A pull request should have one clear purpose, explain the user or maintainer +value, and avoid unrelated cleanup. Include: + +- the problem and why it is worth solving; +- the approach and important tradeoffs; +- tests or a concrete explanation when tests do not apply; +- documentation and changelog updates when behavior changes; +- exact validation commands and results; +- screenshots or recordings for visible UI changes. + +Generated, formatting-only, speculative, or low-signal changes may be closed +when their maintenance cost exceeds their value. Adding tests is welcome when +the tests cover meaningful behavior, failure cases, or a regression—not merely +implementation details already exercised elsewhere. + +If AI tools materially assisted the change, review every line yourself and say +so in the pull request. The contributor remains responsible for correctness, +licensing, security, and responding to review. + +## Development workflow + +1. Fork the repository and create a focused branch. +2. Follow its `README`, `CONTRIBUTING.md`, and `AGENTS.md`. +3. Add or update tests before changing behavior when practical. +4. Run the repository's documented formatter, linter, tests, and validation. +5. Open a pull request using the template and keep the branch current. + +Do not include secrets, private data, proprietary code, or dependencies whose +license is incompatible with the repository. + +## Review and acceptance + +Maintainers may ask for a narrower change, additional evidence, or a different +design. Approval does not guarantee immediate merge or release. Maintainers may +close a pull request that is out of scope, inactive, unsafe, duplicative, or too +costly to maintain; this is about project fit, not the contributor's worth. diff --git a/OPEN_SOURCE_MAINTENANCE.md b/OPEN_SOURCE_MAINTENANCE.md new file mode 100644 index 0000000..bfdb2eb --- /dev/null +++ b/OPEN_SOURCE_MAINTENANCE.md @@ -0,0 +1,47 @@ +# ShakaCode open-source maintenance baseline + +This is the public baseline for actively maintained ShakaCode repositories. +Repository-specific requirements may be stricter. + +## Repository setup + +- Use `main` for new repositories. Rename an existing default branch only + through an explicit migration that checks CI, releases, deployments, badges, + documentation, and downstream consumers. +- Delete head branches after merge. +- Prefer squash merge; disable merge commits unless release history requires them. +- Protect the default branch against force pushes and deletion. +- Require pull requests for maintained projects. Flagship projects normally + require at least one approval and resolved review conversations. +- Give workflows the smallest permissions they need and pin sensitive + third-party actions to reviewed versions or commit SHAs. +- Enable private vulnerability reporting, dependency alerts, and automated + dependency updates when supported. +- Keep topics, description, website, license, ownership, and archive status current. + +## Maintained repository contents + +Normally provide a README, license, contribution guide, code of conduct, +security policy, support guidance, issue/PR templates, CI, and an `AGENTS.md` +with real setup and validation commands. + +## Lifecycle review + +Inactivity is a signal, not an automatic archive decision: + +- review classification after about six months without a push; +- mark for maintainer attention after one year; +- consider archival after two years; +- give repositories over five years without activity especially strong review. + +Before archiving, check package downloads, dependents, releases, deployments, +support/security commitments, whether the project is intentionally stable, and +whether a replacement exists. Update the README and links before archiving. +Never delete or archive solely because a timer elapsed. + +## Outside contributions + +Treat fork pull requests as untrusted input. Review metadata and the complete +diff before running contributor-controlled code with credentials. Do not expose +secrets to fork workflows. A contribution should earn its long-term maintenance +cost through clear user value, meaningful coverage, or reduced risk. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..f219539 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,31 @@ +# ShakaCode default security policy + +Repository-specific security policies and supported-version statements take +precedence over this organization default. + +## Reporting a vulnerability + +Do not open a public issue, discussion, or pull request for a suspected +vulnerability. + +Use the affected repository's **Security** tab and select **Report a +vulnerability** when private vulnerability reporting is available. Include the +affected versions, impact, and the smallest safe reproduction you can share +privately. + +If no private reporting form is available, email +[contact@shakacode.com](mailto:contact@shakacode.com) with the subject +`Security report: OWNER/REPOSITORY`. In the first message, include only the +repository, affected version range, and a brief impact description. Wait for a +private channel before sending exploit details, credentials, customer data, or +proof-of-concept payloads. + +We aim to acknowledge reports within five business days. Please allow +maintainers reasonable time to investigate and coordinate a fix before public +disclosure. + +## Supported versions + +Unless the affected repository documents a different window, maintainers focus +security fixes on the latest stable release. Reports against older versions are +still welcome; remediation may require upgrading. diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..2b69eff --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,14 @@ +# Getting help + +Use the affected repository's issue template for reproducible bugs and its +discussion forum for usage questions when available. Before posting: + +- read the README and current documentation; +- search existing issues and discussions; +- reduce the problem to a minimal reproduction; +- include versions, environment details, expected behavior, and actual behavior. + +Public issue trackers are not appropriate for vulnerabilities, credentials, +private application code, customer data, or paid-support matters. Follow the +security policy for vulnerabilities. For commercial consulting and support, +visit [ShakaCode](https://www.shakacode.com). diff --git a/profile/README.md b/profile/README.md index 9b18d17..eb49b77 100644 --- a/profile/README.md +++ b/profile/README.md @@ -10,6 +10,14 @@ We’re [ShakaCode](https://www.shakacode.com), a global team of open source [cr If you are looking for help with the development and optimization of your project, ShakaCode can help you to take the reliability and performance of your app to the next level. +## Open-source collaboration + +We welcome focused, well-tested contributions. Start with the repository's own +instructions, then see our organization-wide +[contribution guide](../CONTRIBUTING.md), +[security policy](../SECURITY.md), and +[maintenance baseline](../OPEN_SOURCE_MAINTENANCE.md). + ## Join us If you are a developer interested in working on Ruby on Rails / Rust / TypeScript / ReScript projects, [we're hiring](https://www.shakacode.com/career/)!