From 3f480c627fdf90a0b0ebde6368576d8c76f5e70c Mon Sep 17 00:00:00 2001 From: jp-ayyappan Date: Fri, 13 Feb 2026 22:33:29 -0500 Subject: [PATCH 1/4] Add CC BY 4.0 license and update README Co-Authored-By: Claude Sonnet 4.5 --- LICENSE | 89 +++++++++----------------- README.md | 187 ++++++++++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 189 insertions(+), 87 deletions(-) diff --git a/LICENSE b/LICENSE index c9cd9ecc..26b9f75c 100644 --- a/LICENSE +++ b/LICENSE @@ -1,7 +1,7 @@ -Copyright 2025 Virtru Corporation -This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. +Copyright 2026 Virtru Corporation +This work is licensed under the Creative Commons Attribution 4.0 International License. -Attribution-ShareAlike 4.0 International +Attribution 4.0 International ======================================================================= @@ -36,7 +36,7 @@ exhaustive, and do not form part of our licenses. material not subject to the license. This includes other CC- licensed material, or material used under an exception or limitation to copyright. More considerations for licensors: - wiki.creativecommons.org/Considerations_for_licensors + wiki.creativecommons.org/Considerations_for_licensors Considerations for the public: By using one of our public licenses, a licensor grants the public permission to use the @@ -51,24 +51,22 @@ exhaustive, and do not form part of our licenses. rights in the material. A licensor may make special requests, such as asking that all changes be marked or described. Although not required by our licenses, you are encouraged to - respect those requests where reasonable. More_considerations - for the public: - wiki.creativecommons.org/Considerations_for_licensees + respect those requests where reasonable. More considerations + for the public: + wiki.creativecommons.org/Considerations_for_licensees ======================================================================= -Creative Commons Attribution-ShareAlike 4.0 International Public -License +Creative Commons Attribution 4.0 International Public License By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons -Attribution-ShareAlike 4.0 International Public License ("Public -License"). To the extent this Public License may be interpreted as a -contract, You are granted the Licensed Rights in consideration of Your -acceptance of these terms and conditions, and the Licensor grants You -such rights in consideration of benefits the Licensor receives from -making the Licensed Material available under these terms and -conditions. +Attribution 4.0 International Public License ("Public License"). To the +extent this Public License may be interpreted as a contract, You are +granted the Licensed Rights in consideration of Your acceptance of +these terms and conditions, and the Licensor grants You such rights in +consideration of benefits the Licensor receives from making the +Licensed Material available under these terms and conditions. Section 1 -- Definitions. @@ -87,11 +85,7 @@ Section 1 -- Definitions. and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License. - c. BY-SA Compatible License means a license listed at - creativecommons.org/compatiblelicenses, approved by Creative - Commons as essentially the equivalent of this Public License. - - d. Copyright and Similar Rights means copyright and/or similar rights + c. Copyright and Similar Rights means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or @@ -99,33 +93,29 @@ Section 1 -- Definitions. specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights. - e. Effective Technological Measures means those measures that, in the + d. Effective Technological Measures means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements. - f. Exceptions and Limitations means fair use, fair dealing, and/or + e. Exceptions and Limitations means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material. - g. License Elements means the license attributes listed in the name - of a Creative Commons Public License. The License Elements of this - Public License are Attribution and ShareAlike. - - h. Licensed Material means the artistic or literary work, database, + f. Licensed Material means the artistic or literary work, database, or other material to which the Licensor applied this Public License. - i. Licensed Rights means the rights granted to You subject to the + g. Licensed Rights means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license. - j. Licensor means the individual(s) or entity(ies) granting rights + h. Licensor means the individual(s) or entity(ies) granting rights under this Public License. - k. Share means to provide material to the public by any means or + i. Share means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material @@ -133,13 +123,13 @@ Section 1 -- Definitions. public may access the material from a place and at a time individually chosen by them. - l. Sui Generis Database Rights means rights other than copyright + j. Sui Generis Database Rights means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world. - m. You means the individual or entity exercising the Licensed Rights + k. You means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning. @@ -185,13 +175,7 @@ Section 2 -- Scope. Licensed Rights under the terms and conditions of this Public License. - b. Additional offer from the Licensor -- Adapted Material. - Every recipient of Adapted Material from You - automatically receives an offer from the Licensor to - exercise the Licensed Rights in the Adapted Material - under the conditions of the Adapter's License You apply. - - c. No downstream restrictions. You may not offer or impose + b. No downstream restrictions. You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the @@ -273,24 +257,9 @@ following conditions. information required by Section 3(a)(1)(A) to the extent reasonably practicable. - b. ShareAlike. - - In addition to the conditions in Section 3(a), if You Share - Adapted Material You produce, the following conditions also apply. - - 1. The Adapter's License You apply must be a Creative Commons - license with the same License Elements, this version or - later, or a BY-SA Compatible License. - - 2. You must include the text of, or the URI or hyperlink to, the - Adapter's License You apply. You may satisfy this condition - in any reasonable manner based on the medium, means, and - context in which You Share Adapted Material. - - 3. You may not offer or impose any additional or different terms - or conditions on, or apply any Effective Technological - Measures to, Adapted Material that restrict exercise of the - rights granted under the Adapter's License You apply. + 4. If You Share Adapted Material You produce, the Adapter's + License You apply must not prevent recipients of the Adapted + Material from complying with this Public License. Section 4 -- Sui Generis Database Rights. @@ -305,9 +274,8 @@ apply to Your use of the Licensed Material: b. if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database - Rights (but not its individual contents) is Adapted Material, + Rights (but not its individual contents) is Adapted Material; and - including for purposes of Section 3(b); and c. You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database. @@ -428,3 +396,4 @@ the avoidance of doubt, this paragraph does not form part of the public licenses. Creative Commons may be contacted at creativecommons.org. + diff --git a/README.md b/README.md index a3f04374..dab22880 100644 --- a/README.md +++ b/README.md @@ -1,54 +1,187 @@ -# Website +# OpenTDF Documentation + +> The official documentation website for OpenTDF - an open source toolkit for zero trust, data-centric security. + +## About This Repository + +This repository contains the source code for the [OpenTDF documentation website](https://docs.opentdf.io), built using [Docusaurus](https://docusaurus.io/). The documentation provides comprehensive guides, tutorials, and reference materials for developers and organizations implementing data-centric security with OpenTDF. + +## What is OpenTDF? + +OpenTDF is an open source system for implementing data-centric security that enables: + +- **Zero Trust Data Protection**: Cryptographically bind access control policies to data objects +- **Attribute-Based Access Control (ABAC)**: Fine-grained access decisions based on attributes and context +- **Policy Travels with Data**: Security controls remain attached wherever data goes +- **Trust Data Format (TDF)**: Open standard for self-protecting data + +## Documentation Structure + +Our documentation follows a user-needs approach with four main categories: + +- **🚀 Tutorials**: Step-by-step learning experiences for hands-on practice +- **📖 How-To Guides**: Problem-solving recipes for specific tasks and integrations +- **💡 Explanations**: Conceptual guides covering the "why" behind OpenTDF's design +- **📚 Reference**: Technical specifications, API docs, and lookup information + +## Contributing + +We welcome contributions to improve our documentation! Please see our [Contributing Guide](CONTRIBUTING.md) for guidelines on: + +- Writing and editing documentation +- Style and formatting standards +- Review and approval process +- Technical setup for contributors + +For style guidelines, please refer to our [Style Guide](STYLE_GUIDE.md). + +## Quick Links + +- **Live Documentation**: [docs.opentdf.io](https://docs.opentdf.io) +- **OpenTDF Platform**: [github.com/opentdf/platform](https://github.com/opentdf/platform) +- **TDF Format Spec**: [github.com/opentdf/spec](https://github.com/opentdf/spec) +- **OpenTDF Organization**: [github.com/opentdf](https://github.com/opentdf) +- **Community Discussions**: [GitHub Discussions](https://github.com/opentdf/platform/discussions) + +--- + +## Local Development This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator. -### Installation +### Prerequisites +Before you can run the documentation locally, you'll need Node.js and npm. We recommend using nvm (Node Version Manager) to manage Node.js versions. + +#### Option 1: Using nvm (Recommended) + +nvm allows you to install and switch between different Node.js versions easily. + +**Installation:** + +- **macOS/Linux**: Follow the installation instructions at [nvm GitHub repository](https://github.com/nvm-sh/nvm#installation-and-update) +- **Windows**: Install nvm-windows from [nvm-windows releases](https://github.com/coreybutler/nvm-windows#installation--upgrades) + +**Verify installation:** + +```bash +nvm --version # macOS/Linux +nvm version # Windows ``` -$ nvm use -$ npm ci -``` + +#### Option 2: Direct Node.js Installation + +If you prefer not to use nvm: + +1. **Visit [nodejs.org](https://nodejs.org/)** and download **Node.js version 22** (the version specified in our `.nvmrc` file) +2. **Follow the installation instructions** for your operating system +3. **Verify installation:** + + ```bash + node --version # Should show v22.x.x + npm --version # Should show npm version + ``` + +### Installation + +1. **Clone the repository:** + + ```bash + git clone https://github.com/opentdf/docs.git + cd docs + ``` + +2. **Use the correct Node.js version** (if using nvm): + + ```bash + nvm use # This reads the .nvmrc file and switches to Node.js v22 + ``` + + If you don't have Node.js v22 installed via nvm: + + ```bash + nvm install 22 + nvm use 22 + ``` + +3. **Install dependencies:** + + ```bash + npm ci # Installs exact versions from package-lock.json + ``` ### Local Development -``` -$ npm run start -``` + ```bash + npm run start + ``` This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. ### Build -``` -$ npm run build -``` + ```bash + npm run build + ``` This command generates static content into the `build` directory and can be served using any static contents hosting service. -### Preview Deployment +### Testing with Feature Branches -Deploy to a Surge preview domain for testing changes before merging to production. **A free Surge account is required** - you'll be prompted to sign up the first time you deploy. +The documentation site pulls content from multiple upstream repositories using Docusaurus remote content plugins. By default, content is fetched from the `main` branch of each repository. You can override this behavior using environment variables to test documentation changes from feature branches before they're merged. -**Important:** Each developer should use a unique preview domain name to avoid conflicts. Use a descriptive name based on your ticket number or feature: +**Available Environment Variables:** -```bash -# Build the site -npm run build +- `PLATFORM_BRANCH` - Controls which branch to fetch from `opentdf/platform` (default: `main`) +- `SPEC_BRANCH` - Controls which branch to fetch from `opentdf/spec` (default: `main`) +- `OTDFCTL_BRANCH` - Controls which branch to fetch from `opentdf/otdfctl` (default: `main`) + +**Examples:** -# Deploy to your unique preview URL -# Replace with your ticket number or feature name -npx surge build opentdf-docs-preview-.surge.sh +Test with all feature branches: +```bash +PLATFORM_BRANCH=jps-updates SPEC_BRANCH=jps-updates OTDFCTL_BRANCH=jps-updates npm run build ``` -**Examples:** +Test with a single feature branch: ```bash -# Using ticket number -npx surge build opentdf-docs-preview-dspx-2345.surge.sh +SPEC_BRANCH=feature-branch-name npm run build +``` -# Using feature description -npx surge build opentdf-docs-preview-troubleshooting-updates.surge.sh +Test in development mode with feature branches: +```bash +PLATFORM_BRANCH=my-feature npm run start ``` -Your preview will be available at `https://opentdf-docs-preview-.surge.sh/` +**Use Cases:** + +- **Before merging PRs**: Test how documentation changes from upstream repos will look when integrated +- **Cross-repo changes**: When making coordinated changes across multiple repositories, test the full integration locally +- **Debugging**: Investigate issues with specific branches without affecting your local main branch + +**Note**: The branches must exist in the respective GitHub repositories and be accessible (public or you have access). + +--- + +## License + +This documentation is licensed under the [Creative Commons Attribution 4.0 International License (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/). + +### License Change Notice + +**Effective Date: February 13, 2026** + +This project's documentation license has changed from: +- **Previous:** Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) +- **New:** Creative Commons Attribution 4.0 International (CC BY 4.0) + +**What this means:** +- ✅ You can use, adapt, and share this documentation under any terms +- ✅ You only need to provide attribution to the original work +- ✅ No longer required to share derivative works under the same license (ShareAlike requirement removed) + +**Rationale:** To make the documentation more accessible and easier to integrate into various projects and contexts while maintaining proper attribution. + +All content committed after February 13, 2026 is licensed under CC BY 4.0. Content created before this date was released under CC BY-SA 4.0. -**Note:** The first time you deploy, Surge will prompt you to create a free account or login. +See the [LICENSE](LICENSE) file for the full legal text. From 25b29341076606a3f9aa73ffcd0e9c7629a56ff5 Mon Sep 17 00:00:00 2001 From: jp-ayyappan Date: Sat, 14 Feb 2026 00:32:23 -0500 Subject: [PATCH 2/4] chore: add CC-BY-4.0 license to package.json Add SPDX license identifier to help GitHub recognize the Creative Commons license for documentation. Co-Authored-By: Claude Sonnet 4.5 --- package.json | 1 + 1 file changed, 1 insertion(+) diff --git a/package.json b/package.json index d116f7b2..1442ef0a 100644 --- a/package.json +++ b/package.json @@ -2,6 +2,7 @@ "name": "docs", "version": "0.0.0", "private": true, + "license": "CC-BY-4.0", "scripts": { "docusaurus": "docusaurus", "start": "docusaurus start", From 2a805cee91e783147a8f0e061c019aa9dd267700 Mon Sep 17 00:00:00 2001 From: Jp Ayyappan <108297634+jp-ayyappan@users.noreply.github.com> Date: Wed, 18 Feb 2026 10:10:59 -0500 Subject: [PATCH 3/4] Update README.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index dab22880..f34d1cd0 100644 --- a/README.md +++ b/README.md @@ -140,7 +140,7 @@ The documentation site pulls content from multiple upstream repositories using D Test with all feature branches: ```bash -PLATFORM_BRANCH=jps-updates SPEC_BRANCH=jps-updates OTDFCTL_BRANCH=jps-updates npm run build +PLATFORM_BRANCH=my-platform-feature SPEC_BRANCH=my-spec-feature OTDFCTL_BRANCH=my-cli-feature npm run build ``` Test with a single feature branch: From 6073204635c8d54a65862094f1743af17996fe2a Mon Sep 17 00:00:00 2001 From: jp-ayyappan Date: Wed, 18 Feb 2026 10:15:01 -0500 Subject: [PATCH 4/4] docs: add Surge preview deployment instructions to README Co-Authored-By: Claude Sonnet 4.6 --- README.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/README.md b/README.md index f34d1cd0..f23ac996 100644 --- a/README.md +++ b/README.md @@ -161,6 +161,35 @@ PLATFORM_BRANCH=my-feature npm run start **Note**: The branches must exist in the respective GitHub repositories and be accessible (public or you have access). +### Preview Deployment + +Deploy to a Surge preview domain for testing changes before merging to production. **A free Surge account is required** - you'll be prompted to sign up the first time you deploy. + +**Important:** Each developer should use a unique preview domain name to avoid conflicts. Use a descriptive name based on your ticket number or feature: + +```bash +# Build the site +npm run build + +# Deploy to your unique preview URL +# Replace with your ticket number or feature name +npx surge build opentdf-docs-preview-.surge.sh +``` + +**Examples:** + +```bash +# Using ticket number +npx surge build opentdf-docs-preview-dspx-2345.surge.sh + +# Using feature description +npx surge build opentdf-docs-preview-troubleshooting-updates.surge.sh +``` + +Your preview will be available at `https://opentdf-docs-preview-.surge.sh/` + +**Note:** The first time you deploy, Surge will prompt you to create a free account or login. + --- ## License