From 4e8636986c1f70006b7a137f24d5a5a2b1fe7ce8 Mon Sep 17 00:00:00 2001 From: David Walter Date: Thu, 28 May 2026 09:00: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 | 177 ++++++++++++++++++++++++--------------------- SECURITY.md | 11 +++ SUPPORT.md | 10 +++ agents.md | 71 ++++++++++++++++++ 6 files changed, 205 insertions(+), 81 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 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 2cc6915e..1aa050a2 100644 --- a/README.md +++ b/README.md @@ -1,131 +1,146 @@ +# Android Scenario Testing -[![Tests last execution](https://github.com/owncloud/android-scenario-testing/actions/workflows/e2e.yml/badge.svg)](https://github.com/owncloud/android-scenario-testing/actions/workflows/e2e.yml) + -Scenarios contained in feature files written in Gherkin language. -Available scenarios can be found -[here](src/test/resources/io/cucumber). +[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![ownCloud OSPO](https://img.shields.io/badge/OSPO-ownCloud-blue)](https://kiteworks.com/opensource) -Defined for the [ownCloud Android app](https://github.com/owncloud/android) +This repository contains end-to-end scenario tests for the [ownCloud Android app](https://github.com/owncloud/android). Tests are written as Gherkin feature files using Cucumber for step interpretation and Appium for device interaction. The test suite covers core functionality including login, file operations, sharing, and Spaces, and runs against both oCIS and ownCloud 10 backends. +## Part of Mobile (Android) -## Global overview +This repository provides the automated end-to-end test suite for the [ownCloud Android app](https://github.com/owncloud/android). It is used in CI pipelines to validate app behavior against real server backends. -- Scenarios are defined with [Gherkin -Syntax](https://cucumber.io/docs/gherkin/). +## Getting Started -- Steps are interpreted by [Cucumber](https://cucumber.io/). +Follow the steps below to set up and run the end-to-end test suite. -- Step implementation language: -[Java](https://docs.oracle.com/javase/7/docs/) +### Prerequisites -- Device interaction with [Appium](http://appium.io/) +- An [Appium](https://appium.io/) instance running and reachable +- At least one Android device or emulator attached (verify with `adb devices`) +- `$ANDROID_HOME` environment variable set to the Android SDK folder +### Running Tests -![](architecture.png) +1. Build the [ownCloud Android app](https://github.com/owncloud/android) from the target branch using the `buildAPK` script in `buildapk/` +2. Set environment variables: + - `$OC_SERVER_URL` (mandatory) - ownCloud server URL + - `$APPIUM_URL` (optional, defaults to `localhost:4723`) + - `$UDID_DEVICE` (optional) - device/emulator ID + - `$BACKEND` (optional, defaults to `oCIS`) - `oCIS` or `oC10` +3. Run the `executeTests` script -## Get the code +## Documentation -- With git: +- Feature files are in `src/test/resources/io/cucumber/` +- [Appium documentation](https://appium.io/docs/en/about-appium/getting-started/) +- [Cucumber documentation](https://cucumber.io/docs/gherkin/) -`git clone https://github.com/owncloud/android-scenario-testing.git` +## Reference -- Download a [zip -file](https://github.com/owncloud/android-scenario-testing/archive/master.zip) +Key details from the project's test architecture and configuration: -## Requirements +### Architecture -Different requirements: +Tests use [Gherkin Syntax](https://cucumber.io/docs/gherkin/) scenarios interpreted by [Cucumber](https://cucumber.io/), with step implementations in Java and device interaction via [Appium](http://appium.io/). -* `Appium` instance running and reachable. Check this [link](https://appium.io/docs/en/about-appium/getting-started/?lang=en) to get futher info about Appium. +### Environment Variables -* At least, one device/emulator attached and reachable via adb. Check command -`adb devices` to ensure `Appium` will get the device reference to -interact with it. +| Variable | Required | Default | Description | +|---|---|---|---| +| `$OC_SERVER_URL` | Yes | -- | ownCloud server URL to test against | +| `$APPIUM_URL` | No | `localhost:4723` | Appium server URL | +| `$UDID_DEVICE` | No | -- | Device/emulator ID (from `adb devices`) | +| `$BACKEND` | No | `oCIS` | Backend type: `oCIS` or `oC10` | -* The environment variable `$ANDROID_HOME` needs to be correctly set up, -pointing to the Android SDK folder +### Backend-Specific Tags -## How to test +Since not all tests are suitable for both backends, tests are tagged: +- `@nooc10` -- tests for oCIS only, not suitable for oC10 +- `@noocis` -- tests for oC10 only, not suitable for oCIS -### 1. Build app +Example: `./executeTests -t "not @ignore and not @noocis"` runs tests suitable for oCIS. -First, build the [app](https://github.com/owncloud/android) from the expected branch/commit to get the test object. +### Test Results -The [buildAPK](https://github.com/owncloud/android-scenario-testing/blob/master/buildapk/buildAPK.sh) script will build the app by using the qa variant available in the app. Such variant: +Reports in HTML and JSON formats are generated in the `target/` directory. -- will disable welcome wizard -- will disable the release notes -- will set basic auth as forced authentication method, required to execute the test suites +### Version Matrix -Besides of that, the script also: +| Component | Version | +|---|---| +| Cucumber | 7.31.0 | +| Appium | 3.1.0 | +| Appium UIAutomator2 Driver | 4.2.3 | +| Java Client | 9.4.0 | -- builds a release-signed apk with the given keystore path and pass (check script variables) -- moves the final artifact to the correct place (`/src/test/resources` folder in the current structure) +## Community & Support -As commented, check the script's variables for the proper setup in your own environment or CI system. +**[Star](https://github.com/owncloud/android-scenario-testing)** this repo and **Watch** for release notifications! -In the current repository there will be always an `owncloud.apk` file located in `/src/test/resources`, as example or fallback. +- [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) -### 2. Execute tests +## Contributing -The script `executeTests` will launch the tests. The following environment variables must be set in advance +We welcome contributions! Please read the [Contributing Guidelines](CONTRIBUTING.md) +and our [Code of Conduct](CODE_OF_CONDUCT.md) before getting started. - $OC_SERVER_URL (mandatory): URL of ownCloud server to test against - $APPIUM_URL (optional): Appium server URL. - If Appium Server is not specified, will be used "localhost:4723" - $UDID_DEVICE (optional): ID of the device/simulator to execute the tests onto. - This ID could be get by executing `adb devices` - $BACKEND (optional): oCIS or oC10. If not specified, will be used oCIS. +### Workflow -The script needs some parameters. Check help `executeTests -h` +- **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 -To execute all tests but the ignored ones (or any other tagged ones): +**Do not open a public GitHub issue for security vulnerabilities.** - export UDID_DEVICE=emulator-5554 - export OC_SERVER_URL=https://my.owncloud.server - export APPIUM_URL=localhost:4723 - export BACKEND=oCIS - ./executeTests -t "not @ignore" +Report vulnerabilities at **** -- see [SECURITY.md](SECURITY.md). -The execution will display step by step how the scenario is being executed. +Bug bounty: [YesWeHack ownCloud Program](https://yeswehack.com/programs/owncloud-bug-bounty-program) -** the `not @ignore` option is set by default +## License -More info in [Cucumber reference](https://cucumber.io/docs/cucumber/api/) +This project is licensed under the [MIT](LICENSE). -**NOTE**: Since there are two kinds of backends available (oC10, oCIS), not all tests are suitable to be executed over both. Those tests have been tagged with: +## About the ownCloud OSPO -- `@nooc10`: tests to be executed only over oCIS, not suitable for oC10. -- `@noocis`: tests to be executed only over oC10, not suitable for oCIS. +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. -It's important to execute the tests with the mentioned tags to avoid wrong positives. Example commands: +- **OSPO Home**: +- **GitHub**: +- **ownCloud**: -`./executeTests -t "not @ignore and not @noocis"`
-This command will execute tests that are not ignored and suitable for oCIS. If this command is run over an oC10 instance, some tests will fail. +For questions about the OSPO or licensing, contact ospo@kiteworks.com. -`./executeTests -t "not @ignore and not @nooc10"`
-This command will execute tests that are not ignored and suitable for oC10. If this command is run over an oCIS instance, some tests will fail. +### License Migration to Apache 2.0 -Every [feature file](https://github.com/owncloud/android-scenario-testing/tree/master/src/test/resources/io/cucumber), and every rule inside every feature file is also tagged, for isolated execution just in case. +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). -## Results +Individual repositories will migrate as their audit is completed. The LICENSE file +in each repo reflects its **current** license status (not the target). -In the folder `target`, you will find a report with the execution results in html and json formats. +**Current license: MIT** (Category A per Apache policy -- permissive, compatible with Apache-2.0). +Migration prerequisites for this repository: -## Versioning - -Up to date: 18/Nov/2025 - -|| | -|:-- |:------:| -| [Cucumber version](https://cucumber.io/docs/installation/java/) | 7.31.0 | -| [Appium version](https://github.com/appium/appium/releases)| 3.1.0 | -| [Appium uiautomator2 driver version](https://github.com/appium/appium-uiautomator2-driver/releases)| 4.2.3 | -| [Java client version](https://github.com/appium/java-client/releases) | 9.4.0 | - -**Note**: This repository was forked from [Cucumber-java -skeleton](https://github.com/cucumber/cucumber-java-skeleton) -repository, which contains the base skeleton to start working. +- **CLA/DCO coverage**: All past contributors must have signed agreements permitting relicensing +- **Header updates**: All source file headers must be updated from MIT to Apache-2.0 notice +- **Dependency audit**: Verify no incompatible transitive dependencies 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..ab46cae4 --- /dev/null +++ b/agents.md @@ -0,0 +1,71 @@ +# AI Agent Guidelines for Android Scenario Testing + +This file provides context for AI coding agents (Claude Code, GitHub Copilot, Cursor, etc.) working in this repository. + +## Repository Overview +- **Product family:** Mobile (Android) +- **Primary language(s):** Java, Gherkin +- **Build system:** Gradle +- **Test framework:** Cucumber, Appium, JUnit +- **CI system:** GitHub Actions + +## Architecture & Key Paths +- `src/test/resources/io/cucumber/` - Gherkin feature files +- `src/` - Java step definitions and test infrastructure +- `buildapk/` - Script to build the ownCloud Android app for testing +- `executeTests` - Script to launch the test suite +- `server/` - Server setup and configuration +- `build.gradle` - Gradle build configuration +- `runAppium.sh` - Appium server launcher + +## Development Conventions +- **Branching:** master +- **Commit messages:** DCO sign-off required (`git commit -s`) +- **Code style:** No specific linter configured +- **PR process:** Open a PR against master. All CI checks must pass. + +## Build & Test Commands +```bash +# Build +./gradlew build + +# Test +./executeTests + +# Build APK for testing +./buildapk/buildAPK.sh +``` + +## Important Constraints +- All code contributions must be compatible with the **MIT** 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 Appium server and an Android device/emulator +- Tests require a running ownCloud server (oCIS or OC10) + + +## 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 +- Feature files use Gherkin syntax - follow existing patterns for new scenarios +- Step definitions are in Java - follow existing naming conventions