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 713db4d..efd690a 100644 --- a/README.md +++ b/README.md @@ -1,58 +1,99 @@ -# Libre Graph Api +# Libre Graph API -An API for open Cloud Collaboration. See the [Libre Graph Home](https://libregraph.github.io/) for more details. + -This API is inspired by [Microsoft Graph API](https://developer.microsoft.com/en-us/graph). +[![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) +The canonical OpenAPI specification for the Libre Graph API, an open standard for cloud collaboration inspired by the Microsoft Graph API. This repository contains the YAML/JSON API definitions, documentation templates, and code generation configuration used to produce typed client libraries in Go, PHP, C++/Qt, and TypeScript for consumption by ownCloud Infinite Scale and third-party integrators. -## Goal +## Getting Started -The project goal is to provide an open source standard for open Cloud Collaboration. +Follow the steps below to view or generate code from the API specification. -Libre Graph is open source and open to any open source project that implements endpoints of the API. +### Viewing the Spec +The OpenAPI spec lives in `api/openapi-spec/v1.0.yaml`. You can render it with any OpenAPI viewer or Swagger UI. -## Influence and differences from Microsoft Graph API +### Generating Client Code -Libre Graph API draws significant inspiration from the Microsoft Graph API, -particularly in its approach to providing a unified endpoint for accessing various services and data. -We believe that the model provided by Microsoft Graph API is a robust and efficient way -to facilitate integration and collaboration across different services. +```bash +docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \ + -i local/api/openapi-spec/v1.0.yaml \ + -g \ + -o /local/out/ +``` -However, Libre Graph API is not identical to Microsoft Graph API. -We have made specific extensions and modifications to better suit our needs and goals: +## Documentation -1. **Extended Functionality**: We have added specific endpoints and features unique to our implementation, designed to enhance collaboration and integration within the open source ecosystem. -2. **Custom Extensions**: Certain functionalities have been extended to provide additional features that are not present in the Microsoft Graph API. -3. **Beta Features**: Some endpoints are currently in beta, allowing us to continuously innovate and adapt to user needs before finalizing them. +- [Rendered API Documentation](https://owncloud.dev/libre-graph-api/) +- [Libre Graph Home](https://libregraph.github.io/) +- [OpenAPI Specification](https://swagger.io/specification/) +## Part of ownCloud Infinite Scale -## Specification +Libre Graph is the collaboration API that underpins [ownCloud Infinite Scale (oCIS)](https://github.com/owncloud/ocis). Client SDKs are generated from this spec into dedicated repositories: -The API specification uses the OpenAPI Specification (OAS) standard. +- [libre-graph-api-go](https://github.com/owncloud/libre-graph-api-go) +- [libre-graph-api-php](https://github.com/owncloud/libre-graph-api-php) +- [libre-graph-api-cpp-qt-client](https://github.com/owncloud/libre-graph-api-cpp-qt-client) +- [libre-graph-api-typescript-axios](https://github.com/owncloud/libre-graph-api-typescript-axios) -The [OpenAPI Specification (OAS)](https://swagger.io/specification/) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. +See the [Libre Graph Home](https://libregraph.github.io/) for the full project vision. -An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases. +This component is part of the [oCIS Docker image](https://hub.docker.com/r/owncloud/ocis). -## Documentation +## Community & Support -You can find a rendered version of the [API documentation](https://owncloud.dev/libre-graph-api/) in our dev docs. +**[Star](https://github.com/owncloud/libre-graph-api)** this repo and **Watch** for release notifications! -## Clients +- [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) -Client code can be generated from the API spec. +## Contributing -For example, to run the generator for the C++ bindings locally, run the following docker-based command: -```bash -docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate --enable-post-process-file -t local/templates/cpp-qt-client -i local/api/openapi-spec/v1.0.yaml -g cpp-qt-client -o /local/out/cpp -``` -That generates the output in out/cpp. +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/*`), 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 + +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**: -### Available client libraries -- [C++/Qt](https://github.com/owncloud/libre-graph-api-cpp-qt-client) -- [go](https://github.com/owncloud/libre-graph-api-go) -- [php](https://github.com/owncloud/libre-graph-api-php) -- [typescript-axios](https://github.com/owncloud/libre-graph-api-typescript-axios) +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..395ab3a --- /dev/null +++ b/agents.md @@ -0,0 +1,59 @@ +# agents.md -- Libre Graph API + +## Repository Overview + +Canonical OpenAPI specification for the Libre Graph API, an open cloud collaboration standard inspired by the Microsoft Graph API. Licensed under Apache-2.0. Client libraries are generated from this spec. + +## Architecture & Key Paths + +- `api/` -- OpenAPI specification files (YAML/JSON) +- `templates/` -- Code generation templates +- `docs/` -- Generated documentation +- `composer.json` -- PHP dependencies (for documentation tooling) +- `index.html` -- Landing page + +## Development Conventions + +- OpenAPI Specification (OAS) standard +- Code generation via OpenAPI Generator +- API changes should be backward-compatible when possible + +## Build & Test Commands + +```bash +# Generate client code (example for C++): +docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \ + -t local/templates/cpp-qt-client \ + -i local/api/openapi-spec/v1.0.yaml \ + -g cpp-qt-client \ + -o /local/out/cpp +``` + +## Important Constraints + +- Licensed under Apache-2.0 (already at the OSPO target license). The broader ownCloud organization is migrating other repositories from copyleft licenses to Apache 2.0. +- Changes to the spec affect all generated client libraries (Go, PHP, C++/Qt, TypeScript). +- All contributions require a DCO sign-off. + + +## 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 + +This is the source-of-truth for the Libre Graph API. Any spec changes here trigger regeneration of client libraries in libre-graph-api-go, libre-graph-api-php, libre-graph-api-cpp-qt-client, and libre-graph-api-typescript-axios. Spec modifications must preserve backward compatibility.