diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..ce144bf1 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,8 @@ +# Code of Conduct + +This project follows the ownCloud Code of Conduct. + +Please read the full Code of Conduct at: +**** + +By participating in this project, you agree to abide by its terms. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..65c99156 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,9 @@ +# Contributing + +Thank you for your interest in contributing to this project! + +Please read the full contributing guidelines at: +**** + +For development setup, coding standards, and pull request process, +see the README in this repository. diff --git a/README.md b/README.md index 54465306..001bc98a 100644 --- a/README.md +++ b/README.md @@ -1,45 +1,98 @@ -# Infinite Scale Documentation +# ownCloud Infinite Scale Documentation -**IMPORTANT** + -Since April 2026, this repository requires [Commit Signing](https://docs.github.com/articles/about-gpg) and uses [Conventional Commits](https://www.conventionalcommits.org) for commits and the Pull Request title. +[![License](https://img.shields.io/badge/License-See%20Repository-blue.svg)](LICENSE) [![ownCloud OSPO](https://img.shields.io/badge/OSPO-ownCloud-blue)](https://kiteworks.com/opensource) -**Table of Contents** +Antora-based documentation component for ownCloud Infinite Scale (oCIS). This repository contains the AsciiDoc source files for the oCIS administrator documentation, including service configuration, deployment guides, and environment variable references. It is built as part of the [main docs site](https://github.com/owncloud/docs) and published to [doc.owncloud.com](https://doc.owncloud.com). -* [Building the Infinite Scale Docs](#building-the-infinite-scale-docs) -* [General Notes](#general-notes) -* [Generating the Documentation](#generating-the-documentation) -* [Important Notes](#important-notes) -* [Target Branch and Backporting](#target-branch-and-backporting) -* [Branching Workflow](#branching-workflow) -* [Create a New Version Branch for Infinite Scale](#create-a-new-version-branch-for-infinite-scale) +## Getting Started -## Building the Infinite Scale Docs +To preview changes locally: -The Infinite Scale documentation is not built independently. Instead, it is built together with the [main documentation](https://github.com/owncloud/docs/). However, you can build a local copy of the Infinite Scale documentation to preview changes you are making. +```bash +npm install +npm run antora-local +npm run serve +``` -Whenever a Pull Request of this repo gets merged, it automatically triggers a full docs build. +This generates a standalone preview at `http://localhost:8080`. For the full site build, merge your changes and the [docs](https://github.com/owncloud/docs) repository will automatically rebuild. -## General Notes +**Important:** When the oCIS dev team creates a new service, a corresponding documentation page must be added in the services folder to prevent cross-reference build errors. -To make life easier, most of the content written in [docs](https://github.com/owncloud/docs#readme) applies also here. For ease of reading, the most important steps are documented here too. For more information see the link provided. Only a few topics of this repo are unique like the branching. +## Documentation -## Generating the Documentation +- [Branching Workflow](./docs/the-branching-workflow.md) +- [Version Branch Creation](./docs/new-version-branch.md) +- [Main Documentation Build](https://github.com/owncloud/docs) +- [oCIS Developer Docs](https://owncloud.dev) -See the [Generating the Documentation](https://github.com/owncloud/docs#generating-the-documentation) in the docs repo for more details as it applies to all documentation repositories. +## Part of ownCloud Documentation -## Important Notes +This is a content component for the [ownCloud docs](https://github.com/owncloud/docs) Antora build. The oCIS source code lives at [owncloud/ocis](https://github.com/owncloud/ocis). Published documentation is available at [doc.owncloud.com](https://doc.owncloud.com) and developer documentation at [owncloud.dev](https://owncloud.dev). -* When the Infinite Scale dev team creates a new service and merges the code, you **must** add a new service page in the services folder using the service name as document name. If this is omitted, **ALL** new and pending doc (!!) PR's will error with `target of xref not found` because of missing reference targets. These references originate in the `env-vars-special-scope.adoc` document which uses sources from the `ocis` repo containing automatically generated content where the referenced target is missing in the admin docs. +## Community & Support -## Target Branch and Backporting +**[Star](https://github.com/owncloud/docs-ocis)** this repo and **Watch** for release notifications! -See the [following section](https://github.com/owncloud/docs#target-branch-and-backporting) as the same rules and notes apply. +- [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) -## Branching Workflow +## Contributing -Please refer to the [Branching Workflow for the Infinite Scale](./docs/the-branching-workflow.md) for more information. +We welcome contributions! Please read the [Contributing Guidelines](CONTRIBUTING.md) +and our [Code of Conduct](CODE_OF_CONDUCT.md) before getting started. -## Create a New Version Branch for Infinite Scale +### Workflow -Please refer to [Create a New Version Branch for Infinite Scale](./docs/new-version-branch.md) for more information. +- **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/*`), or (c) verified in the GitHub Marketplace. + +## Security + +**Do not open a public GitHub issue for security vulnerabilities.** + +Report vulnerabilities at **** -- see [SECURITY.md](SECURITY.md). + +Bug bounty: [YesWeHack ownCloud Program](https://yeswehack.com/programs/owncloud-bug-bounty-program) + +## License + +See [LICENSE](LICENSE) for license details. + +## 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**: +- **GitHub**: +- **ownCloud**: + +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: Not detected.** The OSPO will determine the current license status of this +repository before planning any migration steps. If you know the intended license, please open an +issue or contact ospo@kiteworks.com. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000..78094ae4 --- /dev/null +++ b/SECURITY.md @@ -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: +**** + +You can also report vulnerabilities through our YesWeHack bug bounty program: +**** diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 00000000..d87c0ca8 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,10 @@ +# Support + +For support with this project, please use the following channels: + +- **Enterprise Support**: +- **Community discussions**: https://github.com/orgs/owncloud/discussions +- **Matrix Chat**: +- **Documentation**: + +Please do not use GitHub issues for general support questions. diff --git a/agents.md b/agents.md new file mode 100644 index 00000000..b0573a90 --- /dev/null +++ b/agents.md @@ -0,0 +1,69 @@ +# AI Agent Guidelines for ownCloud Infinite Scale Documentation + +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 +- **Build system:** npm (Antora) +- **Test framework:** broken-link-checker +- **CI system:** GitHub Actions + +## Architecture & Key Paths + +- `antora.yml` -- Antora component descriptor +- `modules/` -- AsciiDoc documentation content modules +- `lib/` -- Helper libraries +- `site.yml` -- Standalone site playbook for local preview +- `package.json` -- npm scripts +- `docs/` -- Documentation about branching and versioning +- `ext-antora/` -- Custom Antora extensions +- `ext-asciidoc/` -- Custom AsciiDoc extensions + +## Development Conventions +- **Branching:** master +- **Commit messages:** DCO sign-off required (`git commit -s`) +- **Code style:** Prettier (for formatting) +- **PR process:** Open a PR against `master`. All CI checks must pass. + +## Build & Test Commands +```bash +# Build +npm run antora + +# Test +npm run linkcheck + +# Lint +Not detected (Prettier config present for formatting) +``` + +## Important Constraints +- All code contributions must be compatible with the **the license specified in the repository** 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 + + +## 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@ # 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 where the repository enforces it. Many repos use squash merge, where the PR title becomes the commit message on the default branch — apply Conventional Commits format to PR titles as well. A reusable 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