Skip to content

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

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

Open
dj4oC wants to merge 1 commit into
base: master
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
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.
212 changes: 86 additions & 126 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,176 +1,136 @@
# ownCloud Documentation UI

**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.

[link-antora-default-ui]: https://gitlab.com/antora/antora-ui-default
[link-antora]: https://antora.org
[link-ui_bundle.zip]: https://minio.owncloud.com/documentation/ui-bundle.zip
[link-readme]: https://github.com/owncloud/docs
[link-git]: https://git-scm.com
[link-node]: https://nodejs.org
[link-gulp-cli]: http://gulpjs.com
[link-git-package]: https://git-scm.com/downloads
[link-nvm]: https://github.com/creationix/nvm
[link-nvm-installation-instructions]: https://github.com/creationix/nvm#installation
[link-preview]: https://github.com/owncloud/docs/blob/master/docs/build-the-docs.md#viewing-the-html-documentation

The `docs-ui` repository is a custom version of the [Antora Default UI][link-antora-default-ui], for the [Antora][link-antora] version of the ownCloud documentation.

**Table of Contents**

* [Info](#info)
* [Contributing](#contributing)
* [Prerequisites](#prerequisites)
* [Git](#git)
* [Node](#node)
* [Install Dependencies](#install-dependencies)
* [Add Packages](#add-packages)
* [Prepared npm Commands](#prepared-npm-commands)
* [Preview](#preview)
* [Preview Changes Using the ownCloud Documentation](#preview-changes-using-the-owncloud-documentation)
* [Previewing Changes using a Demo Antora Build](#previewing-changes-using-a-demo-antora-build)

## Info

Note that in directory `preview-site-src`, the `404.html` file is on purpose but `index.html` file is for internal testing purposes only. The file is recreated in the `public/` directory on each `preview` build and served from there. There is no need to change or copy it.
<!-- OSPO-managed README | Generated: 2026-04-16 | v2 -->

## Contributing

If you want to make changes, create a "_feature_" branch off of master, make the required changes, and then create a Pull Request (PR) against the _master_ branch.
If the PR is accepted and merged, a new `ui-bundle.zip` package file will be created and published to `https://minio.owncloud.com/documentation/ui-bundle.zip` as part of the build pipeline.
[![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)

## Prerequisites
A custom Antora UI theme for the official ownCloud documentation. This repository is based on the [Antora Default UI](https://gitlab.com/antora/antora-ui-default) and provides the HTML templates, CSS styles, JavaScript behavior, and assets that define the look and feel of the published documentation at [doc.owncloud.com](https://doc.owncloud.com).

To preview the UI changes or to create a local version of a `ui-bundle.zip`, you need to install the following software on your computer.
## Getting Started

- [git][link-git] (command: `git`)
- [Node][link-node] (command: `node`)
- [Gulp CLI][link-gulp-cli] (command: `gulp`)
Install dependencies and preview the UI:

### git
```bash
npm install
npm run preview
```

First, make sure you have git installed.
To build the UI bundle for production:

```Shell
git --version
```bash
npm run bundle
```

If git is not installed, download and install the [git package][link-git-package] for your system.
The generated `ui-bundle.zip` in `build/` is consumed by the Antora documentation build.

### Node
## Documentation

Next, make sure that you have Node installed.
- [Main Documentation Build](https://github.com/owncloud/docs)
- [Antora UI Documentation](https://docs.antora.org/antora-ui-default/)

```Shell
node --version
```
## Part of ownCloud Documentation

If this command fails with an error, you don't have Node installed.
While you can install Node from the official packages, we strongly recommend that you use [NVM][link-nvm] (Node Version Manager) to install and manage Node.
This repository provides the UI bundle consumed by the [ownCloud docs](https://github.com/owncloud/docs) Antora build. The output `ui-bundle.zip` is referenced in the docs site playbook. Published documentation is available at [doc.owncloud.com](https://doc.owncloud.com).

Follow the [NVM installation instructions][link-nvm-installation-instructions] to set up NVM on your machine.
Once you've installed NVM, open a new terminal and install Node using the following command:
## Development Reference

```Shell
nvm ls-remote | grep "Latest LTS"
Development workflow and build tooling for the UI bundle:

...
v18.20.4 (Latest LTS: Hydrogen)
v20.18.1 (Latest LTS: Iron)
v22.22.0 (Latest LTS: Jod)
v24.14.0 (Latest LTS: Krypton)
```
### Prerequisites

Then install a suitable LTS version, preferrable > v20. You can install as many versions as you like or need, see example below.
- [Git](https://git-scm.com/)
- [Node.js](https://nodejs.org/) (v22 LTS recommended; use [NVM](https://github.com/creationix/nvm) to manage versions)
- npm >= 11.11.0

```Shell
nvm install 22.22.0
```
### Available npm Commands

List the installed versions
| Command | Description |
|---|---|
| `npm run lint` | Lint the UI bundle definition |
| `npm run bundle` | Generate a `ui-bundle.zip` for local use |
| `npm run preview` | Preview the bundle using a demo Antora build at `http://localhost:5252` |

```Shell
nvm ls
-> v22.22.0
default -> 22.22.0 (-> v22.22.0)
### Preview with ownCloud Documentation

...
```
To preview UI changes using the actual ownCloud documentation instead of demo content:

**Info:** The backend to push to the web also uses node v22, see the `.drone.star` file. It is recommended to stay with the same release if possible.
1. Build a local `ui-bundle.zip` with `npm run bundle`
2. Switch to the target documentation repository
3. Run `npm run antora-dev-bundle` in the docs repo

Switch to a specific installed version of Node at any time, use the following command:
See the [Generating the Documentation](https://github.com/owncloud/docs#generating-the-documentation) guide for details.

```Shell
nvm use 22.22.0
```
### Contributing Workflow

**Important:** If you have additional concurrent terminals open, you must close these terminals first and reopen them to use the new setup.
Create a feature branch off `master`, make changes, and submit a PR. When merged, the CI pipeline automatically builds and publishes a new `ui-bundle.zip` to `https://minio.owncloud.com/documentation/ui-bundle.zip`.

To make a particular Node version default in new terminals, type:
## Community & Support

```Shell
nvm alias default 22.22.0
```
**[Star](https://github.com/owncloud/docs-ui)** this repo and **Watch** for release notifications!

Now that you have Node installed, you can proceed with installing the Gulp CLI and npm.
- [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)

### Update npm
## Contributing

`npm` should be at minimum version 11.11.0\
You can check this with `npm -v`. If an update is needed, simply run teh following command. Replace `latest` with a version if you want to lock it.
We welcome contributions! Please read the [Contributing Guidelines](CONTRIBUTING.md)
and our [Code of Conduct](CODE_OF_CONDUCT.md) before getting started.

```Shell
npm install -g npm@latest
```
### Workflow

### Install Dependencies
- **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.

Finally, run the following command to install all dependencies:
## Security

```Shell
npm install
```
**Do not open a public GitHub issue for security vulnerabilities.**

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

If a new package needs to be added, type the following:
Bug bounty: [YesWeHack ownCloud Program](https://yeswehack.com/programs/owncloud-bug-bounty-program)

```Shell
npm -i <package-name>
```

## Prepared npm Commands
## License

To see all prepared npm commands, run the following command `npm run`. This will output all commands with their settings, though this makes readability not easy. See the [npm documentation](https://docs.npmjs.com/cli/v11/using-npm/scripts) for more information.
This project is licensed under the [AGPL-3.0](LICENSE).

Here is the list of commands and when to use them:
## About the ownCloud OSPO

* `npm run lint`
Lint the UI bundle definition
* `npm run bundle`
Generate a new `ui-bundle.zip` file for local use
* `npm run preview`
Preview the bundle using the gulp. This previews a demo Antora build.
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.

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

### Preview Changes Using the ownCloud Documentation
For questions about the OSPO or licensing, contact ospo@kiteworks.com.

If you want to preview your changes to the UI using the ownCloud documentation instead of demo content then you need to build a local copy of `ui-bundle.zip` and use it when generating the ownCloud documentation in your local development machine.
### License Migration to Apache 2.0

* First create a local `ui-bundle.zip` with the command described above.
* Then change into the respective documentation repository and run `npm run antora-dev-bundle`.
See the [Generating the Documentation](https://github.com/owncloud/docs#generating-the-documentation) description for more details.
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).

### Previewing Changes using a Demo Antora Build
Individual repositories will migrate as their audit is completed. The LICENSE file
in each repo reflects its **current** license status (not the target).

The following example runs a demo Antora **build** (_not ownCloud_) for the documentation site which can be **accessed** on your local development machine at `http://localhost:5252`.
**Current license: AGPL-3.0** (Category X per Apache policy -- cannot be included in Apache-2.0 works).

To view your changes as you are working on them, run the following command:
Migration prerequisites for this repository:

```Shell
npm run preview
```
- **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.
67 changes: 67 additions & 0 deletions agents.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
# AI Agent Guidelines for ownCloud Documentation UI

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):** CSS
- **Build system:** npm (Gulp)
- **Test framework:** Gulp lint task
- **CI system:** GitHub Actions

## Architecture & Key Paths

- `src/` -- UI source files (Handlebars templates, CSS, JS)
- `tasks/` -- Gulp task definitions
- `gulpfile.js` -- Gulp build configuration
- `preview-site-src/` -- Preview site source for local testing
- `package.json` -- npm scripts
- `docs/` -- Documentation about the UI

## Development Conventions
- **Branching:** master
- **Commit messages:** DCO sign-off required (`git commit -s`)
- **Code style:** Not detected
- **PR process:** Open a PR against `master`. All CI checks must pass.

## Build & Test Commands
```bash
# Build
npm run bundle

# Test
npm run lint

# Lint
npm run lint
```

## Important Constraints
- All code 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


## 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 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