From e9a44e3b9ad153ea4c6fab2f59cee67cf9f6d12b Mon Sep 17 00:00:00 2001 From: Marsh Gardiner Date: Sat, 22 Nov 2025 15:53:11 -0800 Subject: [PATCH 1/6] fixing out of date guidance Updated contributing guidelines to clarify the process for editing AEP rules and submitting PRs. Removes out-of-date information about the site generator and points to our dedicated repo. --- CONTRIBUTING.md | 59 +++++++++---------------------------------------- 1 file changed, 10 insertions(+), 49 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8fc50304..7048a0e4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,62 +1,23 @@ # Contributing -We'd love to accept your patches and contributions to this project. +We welcome patches and contributions to this project. -## Importing an AEP from google.aip.dev +## Editing AEP Rules -Currently, the project is focused on adopting AIPs from -https://google.aip.dev/. You can contribute! +If you spot a minor issue that seems to be a mistake, such as a typo, please make an PR with a fix. -You can -[watch the video walkthrough](https://drive.google.com/file/d/1hCBxfTJPINVUpTLnzccJy4pFXZhQQMd3/view?usp=sharing), -or follow the step by step guide: +For any substantive change or new rule proposal, it is best to search the [discussions](https://github.com/aep-dev/aeps/discussions) +for similar topics before opening a new one. Lighter weight discussions also happen in #aep channel +in the CNCF Slack is another place or in our weekly Friday calls for quick validation of the concept. -1. [Select an AIP to adopt into an AEP from the open issues with the label "adoption"](https://github.com/aep-dev/aep.dev/labels/adoption). - - Consider - [ones also with the label "good first issue"](https://github.com/aep-dev/aep.dev/issues?q=is%3Aopen+label%3A%22good+first+issue%22+label%3Aadoption). -1. Navigate to the - [GitHub Repository](https://github.com/aip-dev/google.aip.dev), and find the - AIP in the - [general directory](https://github.com/aip-dev/google.aip.dev/tree/master/aip/general). - Copy the raw content. -1. Create a directory for the aep, and update the aep.yaml file to "approved". - [Full example PR](https://github.com/aep-dev/aep.dev/pull/77/files). -1. Modify the content from the aip markdown and paste over the aep.md content. - - Remove any Google-isms (e.g. replace Google domains with example.com). - - Extend any proto-specific guidance to include both OpenAPI and proto. - representations. -1. Create a GitHub PR. A reviewer should be with you in 24 hours. - - If a reviewer does not review within that time, please ping @rofrankel or - @toumorokoshi. - - Leave comments on any parts of the text that you would like to discuss. -1. Come say hi in our various communication channels documented in the - [README](README.md#learn-and-connect). - -Some tips: - -- Less is more. If there's a hard disagreement about particular guidance, - consider filing a follow-up issue to get the agreed upon guidance merged. -- Perfect is the enemy of good. Feel free to submit PRs that are mostly there, - and leave questions so reviewers can help address any questions or concerns. +Once there is a clear point of view articulated and some amount of support gathered, the next step +would be to open a PR to reference the discussion and describe the work to be done. Any subsequent +pull request should then reference the issue and will enter the queue for review. ## Development Environment If you are contributing AEP content (rather than code) and want to be able to -view it in your browser, the easiest way to do so is to run the site-generator -script. - -We use [GitHub Pages][1] to make this documentation available, and a specific -[site generator][2] to build the site. - -Run `./scripts/serve.sh` to: - -- clone the site-generator repository. -- run the appropriate npm commands. -- begin the dev server at port 4321. - -### Hot reloading - -The development server currently does not support hot reloading. +view it in your browser, the easiest way to do so is to use our [site-generator project](https://github.com/aep-dev/site-generator). ### Updating examples From d5f2f4267645564d7a52b495654f2404e1b1c4a3 Mon Sep 17 00:00:00 2001 From: Marsh Gardiner Date: Sat, 22 Nov 2025 15:59:54 -0800 Subject: [PATCH 2/6] adding info about our comms channels slack and gcal moved from readme --- CONTRIBUTING.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7048a0e4..6e600575 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,6 +2,16 @@ We welcome patches and contributions to this project. +## Learn and Connect + +If you'd like to get involved in the AEP community, we'd love to have you! The +following channels of communication are available: + +- [The #aep channel in the CNCF Slack](https://cloud-native.slack.com/archives/C04TX46UCTV). + Sign up at https://slack.cncf.io. +- We hold a weekly project meeting on Fridays. See [the AEP Google Calendar, to view any upcoming meetings](https://calendar.google.com/calendar/u/0/embed?src=7e35dd3df194a32f4fa7c03a3454e24ba3651e6f568248efe1ddf1e34a7bee9e@group.calendar.google.com&ctz=America/Los_Angeles) +for details. Options for other times, such as more EU-friendly meetings, can also be arranged. + ## Editing AEP Rules If you spot a minor issue that seems to be a mistake, such as a typo, please make an PR with a fix. From 87b15fb26fa71ee12ef9174796b00fe2799cf62d Mon Sep 17 00:00:00 2001 From: Marsh Gardiner Date: Sat, 22 Nov 2025 16:03:31 -0800 Subject: [PATCH 3/6] Pointing to the aep.dev site content Rather than add clicks to journeys (by visiting a .md file and then the website), this helps people get where they need to be faster. --- README.md | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 64d836e9..415bef74 100644 --- a/README.md +++ b/README.md @@ -5,18 +5,12 @@ of clients and tooling for protobuf and HTTP REST APIs. ## Overview -See [GOVERNANCE.md](./GOVERNANCE.md). +See [Governance](https://aep.dev/governance/). -## Learn and Connect +## Get Involved -If you'd like to get involved in the AEP community, we'd love to have you! The -following channels of communication are available: +There are lots of ways to contribute! See: [Contributing](https://aep.dev/contributing/) -- [The #aep channel in the CNCF Slack](https://cloud-native.slack.com/archives/C04TX46UCTV). - Sign up at https://slack.cncf.io. -- [The AEP Google Calendar, to view any upcoming meetings](https://calendar.google.com/calendar/u/0/embed?src=7e35dd3df194a32f4fa7c03a3454e24ba3651e6f568248efe1ddf1e34a7bee9e@group.calendar.google.com&ctz=America/Los_Angeles) - - A weekly project meeting is held, which anyone interested is welcome to - attend! ## License From 8aac44f76fd9fc042ecb2d512cd2c821c4e8b8b4 Mon Sep 17 00:00:00 2001 From: Marsh Gardiner Date: Sun, 23 Nov 2025 09:21:48 -0800 Subject: [PATCH 4/6] re-add serve.sh adds back instructions for the script for running locally and fixes the broken `fix.py` link --- CONTRIBUTING.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6e600575..cb800841 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,7 +27,11 @@ pull request should then reference the issue and will enter the queue for review ## Development Environment If you are contributing AEP content (rather than code) and want to be able to -view it in your browser, the easiest way to do so is to use our [site-generator project](https://github.com/aep-dev/site-generator). +view it in your browser, the easiest way to do so is to run `./scripts/serve.sh` to: + +- clone the [site-generator project](https://github.com/aep-dev/site-generator) repository +- run the appropriate npm commands +- begin the dev server at port 4321 ### Updating examples @@ -44,7 +48,7 @@ Specifically, the following files are copied over: ### Formatting This repository uses [prettier](https://prettier.io/) and a bespoke script -[scripts/fix.py](scripts/fix.py). Please check the +[scripts/fix.py](https://github.com/aep-dev/aeps/blob/main/scripts/fix.py). Please check the [lint.yaml](https://github.com/aep-dev/aeps/blob/main/.github/workflows/lint.yaml) for the specific file. From 11a15e6ae047ba2aecb4e600940b5abf39ade74f Mon Sep 17 00:00:00 2001 From: Marsh Gardiner Date: Sun, 23 Nov 2025 09:33:26 -0800 Subject: [PATCH 5/6] addresses markdown linting issues Because I was working on a Chromebook, I didn't have an easy way to run the linter on markdown, and the GitHub workflow doesn't give enough insight into what violations it encountered. Luckily there is an online version of [Prettier](https://prettier.io/playground), so I've used that. --- CONTRIBUTING.md | 33 +++++++++++++++++++++------------ 1 file changed, 21 insertions(+), 12 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cb800841..8492fbad 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,27 +9,35 @@ following channels of communication are available: - [The #aep channel in the CNCF Slack](https://cloud-native.slack.com/archives/C04TX46UCTV). Sign up at https://slack.cncf.io. -- We hold a weekly project meeting on Fridays. See [the AEP Google Calendar, to view any upcoming meetings](https://calendar.google.com/calendar/u/0/embed?src=7e35dd3df194a32f4fa7c03a3454e24ba3651e6f568248efe1ddf1e34a7bee9e@group.calendar.google.com&ctz=America/Los_Angeles) -for details. Options for other times, such as more EU-friendly meetings, can also be arranged. +- We hold a weekly project meeting on Fridays. See + [the AEP Google Calendar, to view any upcoming meetings](https://calendar.google.com/calendar/u/0/embed?src=7e35dd3df194a32f4fa7c03a3454e24ba3651e6f568248efe1ddf1e34a7bee9e@group.calendar.google.com&ctz=America/Los_Angeles) + for details. Options for other times, such as more EU-friendly meetings, can + also be arranged. ## Editing AEP Rules -If you spot a minor issue that seems to be a mistake, such as a typo, please make an PR with a fix. +If you spot a minor issue that seems to be a mistake, such as a typo, please +make an PR with a fix. -For any substantive change or new rule proposal, it is best to search the [discussions](https://github.com/aep-dev/aeps/discussions) -for similar topics before opening a new one. Lighter weight discussions also happen in #aep channel -in the CNCF Slack is another place or in our weekly Friday calls for quick validation of the concept. +For any substantive change or new rule proposal, it is best to search the +[discussions](https://github.com/aep-dev/aeps/discussions) for similar topics +before opening a new one. Lighter weight discussions also happen in #aep +channel in the CNCF Slack is another place or in our weekly Friday calls for +quick validation of the concept. -Once there is a clear point of view articulated and some amount of support gathered, the next step -would be to open a PR to reference the discussion and describe the work to be done. Any subsequent -pull request should then reference the issue and will enter the queue for review. +Once there is a clear point of view articulated and some amount of support +gathered, the next step would be to open a PR to reference the discussion and +describe the work to be done. Any subsequent pull request should then reference +the issue and will enter the queue for review. ## Development Environment If you are contributing AEP content (rather than code) and want to be able to -view it in your browser, the easiest way to do so is to run `./scripts/serve.sh` to: +view it in your browser, the easiest way to do so is to run +`./scripts/serve.sh` to: -- clone the [site-generator project](https://github.com/aep-dev/site-generator) repository +- clone the [site-generator project](https://github.com/aep-dev/site-generator) + repository - run the appropriate npm commands - begin the dev server at port 4321 @@ -48,7 +56,8 @@ Specifically, the following files are copied over: ### Formatting This repository uses [prettier](https://prettier.io/) and a bespoke script -[scripts/fix.py](https://github.com/aep-dev/aeps/blob/main/scripts/fix.py). Please check the +[scripts/fix.py](https://github.com/aep-dev/aeps/blob/main/scripts/fix.py). +Please check the [lint.yaml](https://github.com/aep-dev/aeps/blob/main/.github/workflows/lint.yaml) for the specific file. From 7a178472cb39824ad0ddb0b8903cfc4f5d2f24bc Mon Sep 17 00:00:00 2001 From: Marsh Gardiner Date: Wed, 3 Dec 2025 18:13:13 -0800 Subject: [PATCH 6/6] fix linting issue --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 415bef74..4b86d259 100644 --- a/README.md +++ b/README.md @@ -9,8 +9,8 @@ See [Governance](https://aep.dev/governance/). ## Get Involved -There are lots of ways to contribute! See: [Contributing](https://aep.dev/contributing/) - +There are lots of ways to contribute! See: +[Contributing](https://aep.dev/contributing/) ## License