diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 4b67911..5ec3b6f 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -60,7 +60,7 @@ representative at an online or offline event. Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at -info@geolonia.com. +. All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and security of the @@ -116,7 +116,7 @@ the community. This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, available at -https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. +[https://www.contributor-covenant.org/version/2/0/code_of_conduct.html](https://www.contributor-covenant.org/version/2/0/code_of_conduct.html). Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). @@ -124,5 +124,5 @@ enforcement ladder](https://github.com/mozilla/diversity). [homepage]: https://www.contributor-covenant.org For answers to common questions about this code of conduct, see the FAQ at -https://www.contributor-covenant.org/faq. Translations are available at -https://www.contributor-covenant.org/translations. +[https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq). +Translations are available at [https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations). diff --git a/README.md b/README.md index 9662713..58dffda 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,10 @@ -# Public Organization Profile Repository +# Geolonia Organization Profile & Standards -Github allows to share information about an organization by [customizing its -organization's profile](https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/customizing-your-organizations-profile). +This public repo holds Geolonia’s shared GitHub assets: -Additionally, you can use this repository for: +- Organization profile content in `profile/` +- Community health policies (Code of Conduct, contributing, support, security) +- Shared pull request/issue templates +- Reusable GitHub Actions workflow templates -* Defining [community health files](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/about-community-health-files) -* Providing issue and pull request templates for all repositories in the organization -* Defining GitHub Actions workflows that can be shared across the organization - -This repository is public and can be viewed by anyone. +Docs for usage and maintenance are in TechDocs (see Backstage). diff --git a/catalog-info.yaml b/catalog-info.yaml index a1c389b..74d91d6 100644 --- a/catalog-info.yaml +++ b/catalog-info.yaml @@ -18,3 +18,25 @@ spec: lifecycle: production owner: group:geolonia/operations system: geolonia/standards + dependsOn: + - resource:geolonia/github-workflow-templates + +--- +apiVersion: backstage.io/v1alpha1 +kind: Resource +metadata: + namespace: geolonia + name: github-workflow-templates + title: GitHub Workflow Templates + description: Reusable GitHub Actions templates for TechDocs publishing and automated releases. + tags: + - github-actions + - workflows + links: + - url: https://github.com/geolonia/.github/tree/main/workflow-templates + title: Workflow templates + icon: github +spec: + type: workflow-template + owner: group:geolonia/operations + system: geolonia/standards diff --git a/docs/community-health.md b/docs/community-health.md new file mode 100644 index 0000000..5fac254 --- /dev/null +++ b/docs/community-health.md @@ -0,0 +1,25 @@ +# Community Health Files + +The `.github` repository applies these policies and templates to all Geolonia +repositories automatically: + +- `CODE_OF_CONDUCT.md`: expected behavior and reporting guidance (based on + Contributor Covenant) +- `CONTRIBUTING.md`: contribution flow, code style, and review expectations +- `SUPPORT.md`: how to request help or report issues +- `SECURITY.md`: security contacts and vulnerability reporting process +- Issue templates in `.github/ISSUE_TEMPLATE/`: + - `bug_report.yml`: gathers what happened, expectations, steps to reproduce, + and logs; labels issues with `bug`. + - `feature_request.yml`: captures desired outcome, motivation, alternatives, + and extra context; labels issues with `enhancement`. + - `config.yml`: allows blank issues and points to commercial support. +- `.github/pull_request_template.md`: prompts for linked issue (`Fixes #...`), + summary, and optional tests/docs checklist + +## Maintenance tips + +- Keep contact emails/links current in the policy files. +- When guidelines change, update this repo first so every project inherits the change. +- Avoid repository-specific information here; use project-level overrides if needed. +- Ensure no sensitive information is included, as this repo must remain public. diff --git a/docs/index.md b/docs/index.md index 8cea6c8..3591866 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,25 +1,21 @@ -# Public Organization Profile Docs +# Geolonia `.github` Repository -Welcome to the documentation for the Public Organization Profile repository. -This repository contains resources and information about our public organization -profile, including guidelines, policies, and other relevant documentation. +This repository holds Geolonia’s shared GitHub assets and policies. Use it to +keep organization-wide defaults in one place and reduce duplication across projects. -## Public Profile +## What lives here -TBD +- Organization profile content in `profile/` shown on the GitHub org page +- Community health files (Code of Conduct, contributing, support, security) +- Issue and pull request templates +- Workflow templates for publishing TechDocs and shipping tagged releases -## Issue Templates +**Note**: This repo is named `.github` to leverage GitHub's special handling of this +repository and **it must remain public**. Take care not to include any sensitive +information here. -TBD +## Related pages -## Reusable Workflows - -TBD - -## Workflow Templates - -TBD - -## Release Process - -TBD +- [Community health](community-health.md) +- [Reusable workflows](workflows.md) +- [Organization profile](profile.md) diff --git a/docs/profile.md b/docs/profile.md new file mode 100644 index 0000000..fd5a682 --- /dev/null +++ b/docs/profile.md @@ -0,0 +1,14 @@ +# Organization Profile Content + +The organization profile shown at `https://github.com/geolonia` is rendered +from `profile/README.md`. + +This is the **public** profile for Geolonia, so keep the content professional +and friendly. Ensure that only non-sensitive information is included here. + +## Editing guidance + +- Keep the intro short and friendly; it should work in both languages when possible. +- Link to high-value destinations (site, docs, blog, contact). Avoid deep links + that change often. +- Make sure to only use emoji/formatting that renders correctly on the profile card. diff --git a/docs/workflows.md b/docs/workflows.md new file mode 100644 index 0000000..45d1770 --- /dev/null +++ b/docs/workflows.md @@ -0,0 +1,66 @@ +# Reusable Workflow Templates + +Workflow templates in `workflow-templates/` appear in GitHub’s “New workflow” +picker for Geolonia repos. They call the reusable workflows hosted in this repo +under `.github/workflows/`. + +## Why two workflow locations? + +GitHub displayes templates in`workflow-templates/` to users, but the logic lives +in `.github/workflows/`. Templates point to tagged reusable workflows so that +repos making use of them can pin a version and avoid breakage from changes on `main`. + +| Role | Example | Purpose | +| --- | --- | --- | +| Template | `workflow-templates/publish-techdocs.yml` | Shown in “New workflow”; references a tagged reusable workflow (e.g., `.../reusable-backstage-techdocs.yml@v1`). | +| Entrypoint | `.github/workflows/publish-techdocs.yml` | Listens to triggers (push, tag) and forwards to the reusable workflow with defaults. | +| Reusable | `.github/workflows/reusable-backstage-techdocs.yml` | Contains the logic; callable from other repos pinned by tag (`@v1`, SHA). | + +Pinning to tags prevents breakage in repos making use of them. When a breaking +change is needed, publish a new tag (e.g., `v2.1.0`) so repositories can upgrade +on their own schedule. + +## Publish TechDocs (`publish-techdocs.yml`) + +- Runs on `main` when `docs/**` or `mkdocs.yml` changes, or manually via `workflow_dispatch`. +- Delegates to `reusable-backstage-techdocs.yml@v1` with safe defaults for AWS + region, environment, and tool versions. +- Requires `AWS_ACCOUNT_ID` in repo secrets; S3 bucket/role overrides can be + passed through vars or workflow inputs if needed. + +Example minimal usage after selecting the template: + +```yaml +jobs: + publish: + uses: geolonia/.github/.github/workflows/reusable-backstage-techdocs.yml@v1 + with: + environment: production + aws_region: ap-northeast-1 + secrets: + AWS_ACCOUNT_ID: ${{ secrets.AWS_ACCOUNT_ID }} +``` + +## Release on Tag (`release-auto-on-tag.yml`) + +- Triggers on semver-like tags (`v*.*.*`). +- Delegates to `reusable-release-auto-on-tag.yml@v1` to create releases and move + major/minor tags if configured. +- Inherits calling-repo secrets; optional inputs allow toggling prereleases, + generating release notes, or customizing the tag regex. + +Example minimal usage: + +```yaml +jobs: + publish: + uses: geolonia/.github/.github/workflows/reusable-release-auto-on-tag.yml@v1 + secrets: inherit +``` + +## Updating templates + +- Keep the `.properties.json` metadata in sync with the YAML so the workflow + picker shows accurate names/descriptions. +- Bump the referenced reusable workflow version (`@v1`, SHA, or tag) when making + breaking changes. diff --git a/mkdocs.yml b/mkdocs.yml index 99810fc..8fad62d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,6 +1,9 @@ site_name: Public Organization Profile Docs -# nav: -# - Home: index.md +nav: + - Overview: index.md + - Community Health: community-health.md + - Workflows: workflows.md + - Organization Profile: profile.md docs_dir: docs theme: name: material