Skip to content

docs(ospo): community health rollout v2 — LICENSE, README, agents.md, health files #97

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dj4oC merged 6 commits into from
Aug 21, 2026
Merged

docs(ospo): community health rollout v2 — LICENSE, README, agents.md, health files #97

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
a36b7ed
docs(ospo): community health rollout v2 — LICENSE, README, agents.md,…
DeepDiver1975 Aug 21, 2026
12ab788
docs(ospo): fix branch model, actions policy, test command and dead link
DeepDiver1975 Aug 21, 2026
37dc252
chore(license): use the non-deprecated SPDX id AGPL-3.0-or-later
DeepDiver1975 Aug 21, 2026
ffefb6f
ci(lint-pr-title): restore the reopened trigger, add a concurrency group
DeepDiver1975 Aug 21, 2026
20e79c5
docs(readme): title the project "ownCloud Documentation"
DeepDiver1975 Aug 21, 2026
953e1f0
docs(ospo): restore the YesWeHack bounty link to match the org baseline
DeepDiver1975 Aug 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions .github/workflows/lint-pr-title.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
name: Lint PR title

on:
pull_request:
# `reopened` is required: without it, closing and reopening a PR leaves the
# check absent rather than carrying it over. `synchronize` is deliberately
# omitted -- a push cannot change the title, so it can only re-run a lint
# whose outcome is already known.
types: [opened, edited, reopened]

permissions:
pull-requests: read

# Scoped per ref, as in ci.yml. Two quick title edits would otherwise race, and
# a superseded failing run finishing last would leave a red check on a title
# that is already valid.
concurrency:
group: lint-pr-title-${{ github.ref }}
cancel-in-progress: true

jobs:

@DeepDiver1975 DeepDiver1975 Aug 21, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No concurrency group, so overlapping runs can leave a stale red check.

Edit a PR title twice in quick succession — a typo fix immediately after the first attempt — and two runs race. If the earlier, failing run reports last, it overwrites the passing status and the PR shows a red "Lint PR title" against a title that is now valid, until someone re-runs it by hand.

ci.yml in this repository already scopes concurrency per ref (with a comment explaining exactly this), so the convention is established:

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
  cancel-in-progress: true

lint:
runs-on: ubuntu-latest
steps:
- uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50 # v6.1.1
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
8 changes: 8 additions & 0 deletions CODE_OF_CONDUCT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# Code of Conduct

This project follows the ownCloud Code of Conduct.

Please read the full Code of Conduct at:
**<https://owncloud.com/contribute/code-of-conduct/>**

By participating in this project, you agree to abide by its terms.
9 changes: 9 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# Contributing

Thank you for your interest in contributing to this project!

Please read the full contributing guidelines at:
**<https://owncloud.com/contribute/>**

For development setup, coding standards, and pull request process,
see the README in this repository.
661 changes: 661 additions & 0 deletions LICENSE
View file
Open in desktop

Large diffs are not rendered by default.

81 changes: 78 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,22 @@
# ownCloud Docs — Monorepo (experimental)
# ownCloud Documentation

<!-- OSPO-managed README | Generated: 2026-08-21 | v2 -->

[![License](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE) [![ownCloud OSPO](https://img.shields.io/badge/OSPO-ownCloud-blue)](https://kiteworks.com/opensource)

Consolidated, single-repository prototype of the ownCloud documentation. It
replaces the previous 9-repo setup (1 orchestrator + 7 content repos + a custom
UI repo) with **one monorepo** built by Antora.

Live (GitHub Pages): https://deepdiver1975.github.io/owncloud-docs-monorepo/
Live (GitHub Pages): https://doc.owncloud.com

@DeepDiver1975 DeepDiver1975 Aug 21, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The README now advertises a URL that site.yml does not publish to.

This line points at https://doc.owncloud.com, but site.yml:6 still sets site.url to https://deepdiver1975.github.io/owncloud-docs-monorepo. Antora derives both the <link rel="canonical"> on every page and the sitemap.xml entries (via antora-extensions/sitemap-cleanup.js) from site.url — so every page served from doc.owncloud.com would declare the personal fork host as canonical, and the sitemap would advertise only fork URLs. That is the classic way to get a production site deindexed in favour of a URL that isn't the publish target.

The PR description defers the site.yml change to a follow-up, but this line is what turns a latent mismatch into a published promise, so the two should land together. Setting site.url: https://doc.owncloud.com is safe with respect to the go.php compatibility layer — resolveGoPhp derives its base path from location.pathname at runtime, so the redirects survive any base-path change.


## What changed vs. the legacy setup

@DeepDiver1975 DeepDiver1975 Aug 21, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section (the table row at line 19) still documents the branch model as "master only", contradicting agents.md:28 added in this same PR.

agents.md:28 says Branching: main, and main is in fact this repository's default branch. A contributor — or an AI agent, which is precisely the audience agents.md targets — who trusts the README will try to branch from or target master, which does not exist here. Two files changed by one PR should not disagree about something this basic.


| Area | Legacy | Here |
|------|--------|------|
| Repos | 9 | 1 (this repo) |
| Versions | git branches + backporting | **folders** under `content/<product>/<version>/` |
| Branch model | `master` + N version branches per repo | `master` only |
| Branch model | `master` + N version branches per repo | `main` only |
| Search | Elasticsearch + custom index extension + CI secrets | **Pagefind** (static, build-time) |
| UI | custom Gulp/Browserify/jQuery `docs-ui` + `ui-bundle.zip` | **stock Antora default UI** + `ui/supplemental/` |
| Content sources | 7 remote GitHub repos × branches | local folders, authored here (upstream mirror retired) |
Expand Down Expand Up @@ -164,3 +168,74 @@ npm run serve # http-server on :8080
```

Node 22 is recommended (matches CI).

## Community & Support

**[Star](https://github.com/owncloud/docs.owncloud.com)** this repo and **Watch** for release notifications!

- [ownCloud Website](https://owncloud.com)
- [Community Discussions](https://github.com/orgs/owncloud/discussions)
- [Matrix Chat](https://app.element.io/#/room/#owncloud:matrix.org)
- [Documentation](https://doc.owncloud.com)
- [Enterprise Support](https://owncloud.com/contact-us/)
- [OSPO Home](https://kiteworks.com/opensource)

## Contributing

We welcome contributions! Please read the [Contributing Guidelines](CONTRIBUTING.md)
and our [Code of Conduct](CODE_OF_CONDUCT.md) before getting started.

### Workflow

- **Rebase Early, Rebase Often!** We use a rebase workflow. Always rebase on the target branch before submitting a PR.
- **Dependabot**: Automated dependency updates are managed via Dependabot. Review and merge dependency PRs promptly.
- **Signed Commits**: All commits **must** be PGP/GPG signed. See [GitHub's signing guide](https://docs.github.com/en/authentication/managing-commit-signature-verification).
- **DCO Sign-off**: Every commit must carry a `Signed-off-by` line:
```
git commit -s -S -m "your commit message"
```
- **GitHub Actions Policy**: Workflows may only use actions that are (a) owned by `owncloud`, (b) created by GitHub (`actions/*`), (c) verified in the GitHub Marketplace, or (d) verified by the ownCloud Maintainers. Pin every action to its full commit SHA.

## Security

**Do not open a public GitHub issue for security vulnerabilities.**

Report vulnerabilities at **<https://security.owncloud.com>** -- see [SECURITY.md](SECURITY.md).

Bug bounty: [YesWeHack ownCloud Program](https://yeswehack.com/programs/owncloud-bug-bounty-program)

## License

This project is licensed under the [AGPL-3.0](LICENSE).

## About the ownCloud OSPO

The [Kiteworks Open Source Program Office](https://kiteworks.com/opensource), operating under
the [ownCloud](https://owncloud.com) brand, launched on May 5, 2026, to steward the open source
ecosystem around ownCloud's products. The OSPO ensures transparent governance, license compliance,
community health, and sustainable collaboration between the open source community and
[Kiteworks](https://www.kiteworks.com), which acquired ownCloud in 2023.

- **OSPO Home**: <https://kiteworks.com/opensource>
- **GitHub**: <https://github.com/owncloud>
- **ownCloud**: <https://owncloud.com>

For questions about the OSPO or licensing, contact ospo@kiteworks.com.

### License Migration to Apache 2.0

The OSPO is driving a strategic relicensing of ownCloud repositories toward the
[Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0), following
the [Apache Software Foundation's third-party license policy](https://www.apache.org/legal/resolved.html).

Individual repositories will migrate as their audit is completed. The LICENSE file
in each repo reflects its **current** license status (not the target).

**Current license: AGPL-3.0** (Category X per Apache policy -- cannot be included in Apache-2.0 works).

Migration prerequisites for this repository:

- **CLA/DCO coverage**: All past contributors must have signed agreements permitting relicensing
- **Copyleft dependency audit**: All AGPL/GPL dependencies must be replaced or isolated
- **KDE heritage review**: Any code with KDE-era copyrights requires legal analysis
- **Complete relicensing**: AGPL-3.0 is a strong copyleft license; migration requires full relicensing of all files, not just a header change
11 changes: 11 additions & 0 deletions SECURITY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Security Policy

## Reporting a Vulnerability

**Do NOT open a public GitHub issue for security vulnerabilities.**

Please report security issues responsibly via:
**<https://security.owncloud.com>**

You can also report vulnerabilities through our YesWeHack bug bounty program:
**<https://yeswehack.com/programs/owncloud-bug-bounty-program>**
10 changes: 10 additions & 0 deletions SUPPORT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
# Support

For support with this project, please use the following channels:

- **Enterprise Support**: <https://owncloud.com/contact-us/>
- **Community discussions**: https://github.com/orgs/owncloud/discussions
- **Matrix Chat**: <https://app.element.io/#/room/#owncloud:matrix.org>
- **Documentation**: <https://doc.owncloud.com>

Please do not use GitHub issues for general support questions.
76 changes: 76 additions & 0 deletions agents.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
# AI Agent Guidelines for ownCloud Docs

This file provides context for AI coding agents (Claude Code, GitHub Copilot, Cursor, etc.) working in this repository.

## Repository Overview
- **Product family:** Documentation
- **Primary language(s):** JavaScript, AsciiDoc
- **Build system:** npm (Antora + Pagefind)
- **Test framework:** `node --test` (`npm test`), plus the Antora build itself (`npm run antora`)
- **CI system:** GitHub Actions (build & deploy to GitHub Pages)

## Architecture & Key Paths

This is the consolidated documentation **monorepo**. It supersedes the previous
9-repo setup (1 orchestrator + 7 content repos + a custom UI repo).

- `site.yml` -- Antora playbook; all content sources are local
- `content/<product>/<version>/` -- documentation content; products are `main`, `server`, `webui`, `ocis`, `desktop`, `android`, `ios`
- `antora-extensions/` -- custom Antora extensions (`comp-version`, `latest-alias`, `sitemap-cleanup`, `load-global-site-attributes`)
- `asciidoc-extensions/` -- custom AsciiDoc extensions (`tabs`, `remote-include-processor`)
- `ui/supplemental/` -- supplemental files layered onto the stock Antora default UI
- `global-attributes.yml` -- site-wide AsciiDoc attributes
- `sync/` -- the retired upstream import tooling (`manifest.yml`, `patches/`); kept for provenance
- `test/` -- Node test suite
- `package.json` -- npm scripts

## Development Conventions
- **Branching:** `main`
- **Commit messages:** Conventional Commits; DCO sign-off required (`git commit -s`)
- **PR process:** Open a PR against `main`. All CI checks must pass. PR titles are linted for Conventional Commits format.

## Build & Test Commands
```bash
# Build
npm run antora # Antora site build only
npm run build # Antora build + Pagefind search index

# Test -- build first: 4 of the redirect/alias tests skip themselves without public/
npm run antora && npm test

# Preview
npm run antora-local && npm run serve # http://localhost:8080
```

Node 22 is used in CI.

## Important Constraints
- All contributions must be compatible with the **AGPL-3.0** license
- Do not introduce new **copyleft-licensed dependencies** (GPL, AGPL, LGPL, MPL) without explicit discussion in an issue first. This is especially important for repos migrating to Apache 2.0.
- Do not introduce new dependencies without discussion in an issue first
- **Versions are folders, not branches.** A new documentation version is a new directory under `content/<product>/<version>/` -- never a git branch, and never a backport.
- **The upstream mirror is retired.** Content is authored in this repository. Do not re-introduce a sync from the archived `docs-*` repos.

## OSPO Policy Constraints

### GitHub Actions
- **Only** use actions owned by `owncloud`, created by GitHub (`actions/*`), verified on the GitHub Marketplace, or verified by the ownCloud Maintainers.
- Pin all actions to their full commit SHA (not tags): `uses: actions/checkout@<SHA> # vX.Y.Z`
- Never introduce actions from unverified third parties.

### Dependency Management
- Dependabot is configured for automated dependency updates.
- Review and merge Dependabot PRs as part of regular maintenance.
- Do not introduce new dependencies without discussion in an issue first.

### Git Workflow
- **Rebase policy**: Always rebase; never create merge commits. Use `git pull --rebase` and `git rebase` before pushing.
- **Signed commits**: All commits **must** be PGP/GPG signed (`git commit -S -s`).
- **DCO sign-off**: Every commit needs a `Signed-off-by` line (`git commit -s`).
- **Conventional Commits & Squash Merge**: Use the [Conventional Commits](https://www.conventionalcommits.org/) format. This repository squash-merges, so the PR title becomes the commit message on `main` -- apply Conventional Commits format to PR titles as well. A GitHub Actions workflow enforces this.

## Context for AI Agents
- Match existing code style
- Do not refactor unrelated code in the same PR
- Write tests for new functionality
- Keep PRs focused and atomic
3 changes: 2 additions & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
{
"private": true,
"description": "The ownCloud documentation (consolidated monorepo)",
"homepage": "https://github.com/DeepDiver1975/owncloud-docs-monorepo#readme",
"homepage": "https://github.com/owncloud/docs.owncloud.com#readme",
"license": "AGPL-3.0-or-later",
"scripts": {
"antora": "antora --stacktrace site.yml",
"antora-local": "antora --stacktrace --url http://localhost:8080 site.yml",
Expand Down