From 8c0e927ea06c3c36b557e5e508b7491c2f6ec9fc Mon Sep 17 00:00:00 2001 From: David Walter Date: Thu, 28 May 2026 09:03:48 +0200 Subject: [PATCH] =?UTF-8?q?docs(ospo):=20community=20health=20rollout=20v2?= =?UTF-8?q?=20=E2=80=94=20README,=20agents.md,=20health=20files?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Introduced by the Kiteworks Open Source Program Office (OSPO) on May 5, 2026. Changes: - README.md: rewritten with OSPO v2 template — license-specific migration guidance, Community & Support section, Contributing workflow, Security section pointing to security.owncloud.com + YesWeHack bug bounty - agents.md: AI agent context file with architecture, build commands, and OSPO Policy Constraints (GitHub Actions, Dependabot, Git Workflow) - CODE_OF_CONDUCT.md: redirect to https://owncloud.com/contribute/code-of-conduct/ - CONTRIBUTING.md: redirect to https://owncloud.com/contribute/ - SECURITY.md: redirect to https://security.owncloud.com + YesWeHack - SUPPORT.md: redirect to https://owncloud.com/contact-us/ + channels OSPO: https://kiteworks.com/opensource Signed-off-by: David Walter --- CODE_OF_CONDUCT.md | 8 ++ CONTRIBUTING.md | 9 +++ README.md | 185 +++++++++++++++++++++------------------------ SECURITY.md | 11 +++ SUPPORT.md | 10 +++ agents.md | 77 +++++++++++++++++++ 6 files changed, 201 insertions(+), 99 deletions(-) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md create mode 100644 SUPPORT.md create mode 100644 agents.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..ce144bf --- /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 0000000..65c9915 --- /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 d5fb7ad..b762aab 100644 --- a/README.md +++ b/README.md @@ -1,142 +1,129 @@ -# cs3api-validator +# CS3 API Validator - + -[![Build Status](https://drone.owncloud.com/api/badges/owncloud/cs3api-validator/status.svg)](https://drone.owncloud.com/owncloud/cs3api-validator) -[![Open Source Love](https://badges.frapsoft.com/os/v1/open-source.svg?v=103)](https://github.com/ellerbrock/open-source-badges/) -[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) +[![License](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE) [![ownCloud OSPO](https://img.shields.io/badge/OSPO-ownCloud-blue)](https://kiteworks.com/opensource) [![Docker Hub](https://img.shields.io/docker/pulls/owncloud)](https://hub.docker.com/r/owncloud/ocis) -## End-to-End Test Suite for the CS3 APIs +The CS3 API Validator is an end-to-end test suite for implementations of the [CS3 APIs](https://github.com/cs3org/cs3apis). It runs human-readable Gherkin test scenarios against a CS3 API provider, serving both as a BDD development tool and as a litmus test to verify that an implementation complies with the CS3 API specification. The tool requires only the network address of a running CS3 API provider and has no external dependencies beyond Go. -**This tool will receive a lot of changes before version 1.0.0** +## Part of oCIS -The cs3api-validator is a tool to test implementations of the [CS3Apis](https://github.com/cs3org/cs3apis). It works as standalone software which only needs the address of a running cs3api provider. +This tool is part of the [ownCloud Infinite Scale (oCIS)](https://github.com/owncloud/ocis) ecosystem and is used to validate CS3 API compliance. It helps keep different CS3 API implementations in sync and fosters interoperability across the [CS3 community](https://cs3community.org/). -## Purpose +This component is part of the [oCIS Docker image](https://hub.docker.com/r/owncloud/ocis). -### BDD (Behavior driven development) +## Getting Started -The cs3api-validator can be run locally in a development phase to develop against a well-defined set of basic API operations. It has no external dependencies and runs human-readable gherkin test scenarios. This helps to understand the behavior of the CS3APIs being an additional way of documenting the API in combination with the specification. +Follow the steps below to run the CS3 API validation suite. -### Litmus Testing +### Quick Start -This tool makes it possible to confirm that an implementation of the CS3APIs is compliant to the spec and fulfills the basic operations. This helps the CS3 community to keep different implementations in sync and foster compatibility between them. +```bash +git clone git@github.com:owncloud/cs3api-validator.git +cd cs3api-validator +go test -v # default network address is localhost:9142 +``` -## Contributions +### Adding New Test Features -This is a community driven Open Source Project. We welcome contributions from everyone and we're ready to support you if you have the enthusiasm to contribute. +Add Gherkin feature files to the `features/` directory, then implement the step definitions in Go. Run `go run github.com/cucumber/godog/cmd/godog@master` to see which steps need implementation. -Please use the [issue tracker](https://github.com/owncloud/cs3api-validator/issues) to report problems or propose changes. +## Usage -## Developing +Instructions for running and configuring the CS3 API validation suite: -### Quick start -```shell -git clone git@github.com:owncloud/cs3api-validator.git -cd cs3api-validator -go test -v # default network addr of cs3api provider is localhost:9142 -``` +### Running Tests -### Add features +Run with the built-in `go test` command. The `--endpoint` flag sets the network address of the system under test (defaults to `localhost:9142`): -Add new test steps to the feature files in the `features` directory. +```bash +go test --endpoint=your-addr:port -v +``` -```gherkin -Feature: eat godogs - In order to be happy - As a hungry gopher - I need to be able to eat godogs +To build a standalone test binary: - Scenario: Eat 5 out of 12 - Given there are 12 godogs - When I eat 5 - Then there should be 7 remaining +```bash +go test -c +./cs3api-validator.test --endpoint=your-addr:port ``` -Then run ` go run github.com/cucumber/godog/cmd/godog@master` which will output something similar like this -``` -Feature: eat godogs - In order to be happy - As a hungry gopher - I need to be able to eat godogs - - Scenario: Eat 5 out of 12 # features/godogs.feature:6 - Given there are 12 godogs - When I eat 5 - Then there should be 7 remaining - -1 scenarios (1 undefined) -3 steps (3 undefined) -220.129µs - -You can implement step definitions for undefined steps with these snippets: - -func iEat(arg1 int) error { - return godog.ErrPending -} - -func thereAreGodogs(arg1 int) error { - return godog.ErrPending -} - -func thereShouldBeRemaining(arg1 int) error { - return godog.ErrPending -} - -func InitializeScenario(ctx *godog.ScenarioContext) { - ctx.Step(`^I eat (\d+)$`, iEat) - ctx.Step(`^there are (\d+) godogs$`, thereAreGodogs) - ctx.Step(`^there should be (\d+) remaining$`, thereShouldBeRemaining) -} +### Filtering with Tags + +Use [Godog tags](https://github.com/cucumber/godog#tags) to select which features to run: + +```bash +go test --godog.tags="@smoke" -v ``` -Then copy the new step definition stubs to a *_test.go file and implement the steps. In this project we use a FeatureContext struct to share values between the tests steps. In order to do this we need to use a pointer to the FeatureContext as a function receiver in the test step methods. +### Purpose -```go -func (f *FeatureContext) iEat(arg1 int) error { - return godog.ErrPending -} +- **BDD development**: Run locally during development against a well-defined set of basic CS3 API operations. Human-readable Gherkin scenarios serve as both tests and API documentation. +- **Litmus testing**: Confirm that a CS3 API implementation is spec-compliant and supports basic operations, helping keep different implementations in sync. -func (f *FeatureContext) thereAreGodogs(arg1 int) error { - return godog.ErrPending -} +### Adding New Features -func (f *FeatureContext) thereShouldBeRemaining(arg1 int) error { - return godog.ErrPending -} +1. Add Gherkin feature files to the `features/` directory +2. Run `go run github.com/cucumber/godog/cmd/godog@master` to get step definition stubs +3. Implement steps in a `*_test.go` file using the `FeatureContext` struct as a receiver for sharing state between steps -func InitializeScenario(ctx *godog.ScenarioContext) { - f := &FeatureContext{} - ctx.Step(`^I eat (\d+)$`, f.iEat) - ctx.Step(`^there are (\d+) godogs$`, f.thereAreGodogs) - ctx.Step(`^there should be (\d+) remaining$`, f.thereShouldBeRemaining) -} -``` +## Documentation -## Usage +- [CS3 API specification](https://github.com/cs3org/cs3apis) +- [Godog (Go Cucumber)](https://github.com/cucumber/godog) +- [Gherkin syntax](https://cucumber.io/docs/gherkin/) -### Run with go test +## Community & Support -You can run the tests with the built-in go test command. The command passes its flags to the godog test suite. The test suite needs one flag to be set: The network address of the running system under test. It defaults to `localhost:9142` and you can set it using the ``--endpoint``flag. +**[Star](https://github.com/owncloud/cs3api-validator)** this repo and **Watch** for release notifications! -> **_NOTE:_** If you want to use the godog flags you need to prefix them with ``godog.flagname``. +- [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) -#### In a working go environment +## Contributing -Run ``go test --endpoint=your-addr:port -v`` +We welcome contributions! Please read the [Contributing Guidelines](CONTRIBUTING.md) +and our [Code of Conduct](CODE_OF_CONDUCT.md) before getting started. -#### Build a binary with the tests +### Workflow -Run ``go test -c``. This will create a ``cs3api-validator.test`` binary. +- **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. -Execute the tests ``./cs3qpi-validator.test --endpoint=your-addr:port`` +## Security -### Use tags +**Do not open a public GitHub issue for security vulnerabilities.** -You can use [tags](https://github.com/cucumber/godog#tags) to filter features which should be executed. `--godog.tags=` +Report vulnerabilities at **** -- see [SECURITY.md](SECURITY.md). + +Bug bounty: [YesWeHack ownCloud Program](https://yeswehack.com/programs/owncloud-bug-bounty-program) ## License -Apache-2.0 +This project is licensed under the [Apache-2.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**: +- **GitHub**: +- **ownCloud**: +For questions about the OSPO or licensing, contact ospo@kiteworks.com. +> **License status:** This repository is already licensed under Apache-2.0 -- the OSPO target license. +> No migration is required. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..78094ae --- /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 0000000..d87c0ca --- /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 0000000..be15bec --- /dev/null +++ b/agents.md @@ -0,0 +1,77 @@ +# AI Agent Guidelines for CS3 API Validator + +This file provides context for AI coding agents (Claude Code, GitHub Copilot, Cursor, etc.) working in this repository. + +## Repository Overview +- **Product family:** oCIS +- **Primary language(s):** Go, Gherkin +- **Build system:** Go modules +- **Test framework:** Godog (Go Cucumber), Go testing +- **CI system:** None detected + +## Architecture & Key Paths +- `features/` - Gherkin feature files (BDD test scenarios) +- `featurecontext/` - Feature context setup +- `steps/` - Go step definitions for Gherkin scenarios +- `helpers/` - Test helper utilities +- `constants/` - Shared constants +- `scenario/` - Scenario management +- `cs3apivalidator.go` - Main validator logic +- `cs3apivalidator_test.go` - Test entry point +- `go.mod` - Go module definition +- `go.sum` - Dependency checksums +- `docker/` - Docker configuration + +## Development Conventions +- **Branching:** main +- **Commit messages:** DCO sign-off required (`git commit -s`) +- **Code style:** No specific linter configured +- **PR process:** Open a PR against main. All CI checks must pass. + +## Build & Test Commands +```bash +# Build +go build ./... + +# Test (requires running CS3 API provider at localhost:9142) +go test -v + +# Run with custom address +go test -v -addr=myserver:9142 + +# Lint +Not detected +``` + +## Important Constraints +- All code contributions must be compatible with the **Apache-2.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 +- Tests require a running CS3 API provider (e.g., oCIS or Reva) + + +## 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 +- New test scenarios should be added as Gherkin feature files in `features/` +- Step definitions are written in Go - follow existing patterns