Create Onboarding new sources#1728
Open
klaraavo wants to merge 1 commit into
Open
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughAdds a new documentation guide page, "Onboarding a new source to an existing tracking plan," to the data-design guides section. The page includes scope/usage guidance, step-by-step onboarding instructions, a common pitfalls checklist, and related docs links, with several inline review placeholders for URL confirmation. ChangesNew Onboarding Guide Documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Member
📝 Changed routes:
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@pages/data-design/guides/Onboarding` new sources:
- Around line 4-5: Resolve the remaining REVIEW placeholder comments in the
onboarding guide by replacing each marked cross-reference with the confirmed
repo URL or the missing content. Check the referenced sections in the document
for the workflow overview link, Codegen overview link, bulk-assign screenshot,
required reviewers link, and inline debugger doc link, and ensure no <!--
REVIEW: ... --> placeholders remain before merge.
- Around line 1-27: Remove the internal draft HTML comment from the docs page
and replace it with the finalized content only; the note block contains planning
chatter and TODOs that should not ship. In the onboarding guide document, add
the required frontmatter at the top using the repo’s docs conventions so the
page has a title, sidebar_label, slug, and description and can render correctly.
Use the page content itself to verify the correct placement, and leave only the
published guide text in the document body.
- Around line 29-116: Replace the hardcoded production-domain links in this
guide with the repo’s relative internal link style throughout the intro, Steps
1-5, and Related docs. Use the same path-based references as other docs files
like define-sources-and-destinations.mdx, updating each Avo workflow, Codegen,
Inspector, branches, and source/destination reference link to relative paths
instead of absolute https://www.avo.app/docs/... URLs.
- Line 1: The onboarding guide file is using an extensionless name, so it won’t
be treated as a page and it should match the draft slug. Rename the current
guide to onboarding-a-new-source.mdx, keeping the content in the same guides
location, so the page is picked up correctly by the documentation system and
aligns with the onboarding-a-new-source slug.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 13d04218-bad0-42f4-a58b-0eab618c8a0f
📒 Files selected for processing (1)
pages/data-design/guides/Onboarding new sources
| @@ -0,0 +1,116 @@ | |||
| <!-- | |||
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Check naming conventions of sibling files in pages/data-design/guides
fd . pages/data-design/guides -t fRepository: avohq/docs
Length of output: 1168
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== files in pages/data-design/guides =="
fd . pages/data-design/guides -t f | sed 's#^\./##' | sort
echo
echo "== pages/data-design/guides/_meta.js =="
cat -n pages/data-design/guides/_meta.js
echo
echo "== nearby docs conventions (extensionless files / slugs) =="
rg -n --glob '!**/node_modules/**' --glob '!**/dist/**' --glob '!**/build/**' \
'slug|_meta|mdx|extensionless|fileName|route|pages/data-design' pages data-design . 2>/dev/null | head -n 200Repository: avohq/docs
Length of output: 26907
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== next.config.mjs =="
cat -n next.config.mjs
echo
echo "== Onboarding new sources (first 80 lines) =="
sed -n '1,80p' 'pages/data-design/guides/Onboarding new sources' | cat -n
echo
echo "== search for pageExtensions / extensionless docs conventions =="
rg -n --glob '!**/node_modules/**' --glob '!**/dist/**' --glob '!**/build/**' \
'pageExtensions|\.mdx?|\bOnboarding new sources\b|slug.*onboarding|onboarding-a-new-source' \
next.config.mjs pages scripts README.md package.jsonRepository: avohq/docs
Length of output: 48976
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== extensionless files under pages/ =="
python3 - <<'PY'
from pathlib import Path
for p in Path('pages').rglob('*'):
if p.is_file() and p.suffix == '':
print(p)
PY
echo
echo "== files in pages/data-design/guides with basename/extension =="
python3 - <<'PY'
from pathlib import Path
for p in sorted(Path('pages/data-design/guides').iterdir()):
if p.is_file():
print(f"{p.name}\t(ext={p.suffix!r})")
PYRepository: avohq/docs
Length of output: 1087
Rename this file to pages/data-design/guides/onboarding-a-new-source.mdx. The current extensionless name won’t be treated as a page, and the draft slug already points to onboarding-a-new-source.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@pages/data-design/guides/Onboarding` new sources at line 1, The onboarding
guide file is using an extensionless name, so it won’t be treated as a page and
it should match the draft slug. Rename the current guide to
onboarding-a-new-source.mdx, keeping the content in the same guides location, so
the page is picked up correctly by the documentation system and aligns with the
onboarding-a-new-source slug.
Comment on lines
+1
to
+27
| <!-- | ||
| Draft v3 — internal notes for the docs PR | ||
|
|
||
| Cross-references marked with <!-- REVIEW: ... --> comments need URL | ||
| confirmation against the repo before merging. | ||
|
|
||
| Suggested placement: | ||
| Primary path: /docs/data-design/onboarding-a-new-source | ||
| IA: top-level under Data Design, alongside (not under) | ||
| start-data-design. It's a workflow guide, not a feature | ||
| reference — earns its own slot. | ||
|
|
||
| Suggested cross-link callouts to add to existing pages (do these as part of | ||
| the same PR or a follow-up): | ||
| - /docs/data-design/start-data-design | ||
| Top-of-page callout: "Already have a tracking plan and adding a new | ||
| source? Start with Onboarding a new source." | ||
| - /docs/data-design/avo-tracking-plan/define-sources-and-destinations | ||
| "See also" link back here. | ||
| - /docs/data-design/avo-tracking-plan/properties (presence section) | ||
| "See also" link to Step 4 of this guide. | ||
| - /docs/data-design/branches/pulling-pushing-items-between-branches | ||
| "See also" link to Step 3 of this guide. | ||
|
|
||
| Frontmatter format not included — please add per this repo's conventions | ||
| (title, sidebar_label, slug, description, etc.). | ||
| --> |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Remove internal draft notes before merge.
This HTML comment block contains internal planning notes (placement, cross-link TODOs, frontmatter reminder) that shouldn't ship in the published doc. Also note line 26 explicitly flags that frontmatter is still missing — without it, the page likely won't route/render correctly on the docs site (title, slug, sidebar_label, description).
📝 Suggested frontmatter (adjust per repo conventions)
---
title: Onboarding a new source to an existing tracking plan
sidebar_label: Onboarding a new source
slug: /data-design/guides/onboarding-a-new-source
description: Guide for adding a new source to an existing Avo tracking plan.
---🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@pages/data-design/guides/Onboarding` new sources around lines 1 - 27, Remove
the internal draft HTML comment from the docs page and replace it with the
finalized content only; the note block contains planning chatter and TODOs that
should not ship. In the onboarding guide document, add the required frontmatter
at the top using the repo’s docs conventions so the page has a title,
sidebar_label, slug, and description and can render correctly. Use the page
content itself to verify the correct placement, and leave only the published
guide text in the document body.
Comment on lines
+4
to
+5
| Cross-references marked with <!-- REVIEW: ... --> comments need URL | ||
| confirmation against the repo before merging. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win
Resolve pending REVIEW placeholder comments before merge.
Several inline <!-- REVIEW: ... --> comments still need URL confirmation or content additions (workflow overview URL, Codegen overview URL, bulk-assign screenshot, required reviewers URL, inline debugger doc link). These are self-flagged as needing action and shouldn't remain in a merged doc.
Also applies to: 45-45, 53-53, 74-74, 84-84, 91-91
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@pages/data-design/guides/Onboarding` new sources around lines 4 - 5, Resolve
the remaining REVIEW placeholder comments in the onboarding guide by replacing
each marked cross-reference with the confirmed repo URL or the missing content.
Check the referenced sections in the document for the workflow overview link,
Codegen overview link, bulk-assign screenshot, required reviewers link, and
inline debugger doc link, and ensure no <!-- REVIEW: ... --> placeholders remain
before merge.
Comment on lines
+29
to
+116
| # Onboarding a new source to an existing tracking plan | ||
|
|
||
| _Use this guide when you've already defined a tracking plan in Avo and you're now adding a new platform, brand, or market source to it. If you're starting from a blank tracking plan, the [Start data design](https://www.avo.app/docs/data-design/start-data-design) guide is the right entry point instead._ | ||
|
|
||
| ## When to use this guide | ||
|
|
||
| Reach for this guide when: | ||
|
|
||
| - You have an existing tracking plan in Avo with events, properties, and (typically) a global taxonomy. | ||
| - You're adding a new source — a new platform (e.g. iOS), a new brand, or a new market — that needs to send some subset of those events. | ||
| - The source has its own implementation timeline that may not match the rest of the plan, and you may want to break the work into smaller branches. | ||
|
|
||
| This is a common pattern when teams are reimplementing tracking, expanding to a new brand, market, or product line, or rolling out Avo in stages across a multi-platform product. If you're starting fresh, use [Start data design](https://www.avo.app/docs/data-design/start-data-design) instead. | ||
|
|
||
| ## How this fits with the broader Avo workflow | ||
|
|
||
| This guide focuses on the Plan and Implement steps of the [Avo workflow](https://www.avo.app/docs/workflow) <!-- REVIEW: confirm canonical URL for the workflow overview doc --> for the specific case of adding a new source. The shape is the same as any other planning work — branch, edit, review, implement, validate, publish — but with source-level decisions (event assignment, property presence per source, branch slicing) layered on top. | ||
|
|
||
| ## Step 1 — Create the source in Avo | ||
|
|
||
| Open a branch and add the new source. See [Define sources and destinations](https://www.avo.app/docs/data-design/avo-tracking-plan/define-sources-and-destinations) for the click-by-click. As you create it, set: | ||
|
|
||
| - **Source name and platform** — match how engineering refers to the codebase (e.g. `web-app`, `ios-app`). | ||
| - **Destinations** — which destinations this source sends to. Often the same as other sources for the same product. | ||
| - **Codegen language and output (if using Codegen)** — see [Avo Codegen overview](https://www.avo.app/docs/implementation/avo-codegen-overview). <!-- REVIEW: confirm canonical URL for Codegen overview --> Configure now so engineering can pick it up later in step 4. | ||
|
|
||
| ## Step 2 — Assign events from the central taxonomy to the source | ||
|
|
||
| On the same branch, walk the event list and add the new source to each event. For larger plans, use bulk-edit on the events list — filter the events you want, select them, and add the source in one operation. | ||
|
|
||
| **Branch strategy:** use one branch per logical grouping — often per market, brand, or product line — depending on how your organization slices ownership. If multiple sources within a group have meaningfully different timelines or reviewers, one branch per source is fine, but per-group keeps coordination simpler. | ||
|
|
||
| **Configure source-specific property behavior.** Once an event is assigned to the source, you can configure each property on that event differently per source: | ||
|
|
||
| - **Presence** — required, optional, or not sent. A property can be required on one source and optional on another. | ||
| - **Allowed values (where it applies)** — a constrained list of values for this source. Useful when the same property has source-specific values. | ||
|
|
||
| Reference: [Configuring when properties are required or optional](https://www.avo.app/docs/data-design/avo-tracking-plan/properties#configuring-when-properties-are-required-or-optional). | ||
|
|
||
| Tips: | ||
|
|
||
| - Default to the global presence and only override where the source genuinely behaves differently — fewer overrides means easier maintenance. | ||
| - Document the reason for each override in the event description so a future reviewer doesn't have to reverse-engineer it. | ||
| - If you find yourself overriding the same property the same way across many events on this source, consider whether the global definition should change instead. | ||
|
|
||
| <!-- REVIEW: consider adding a screenshot of the bulk-assign flow on the events list — most useful place for a visual. --> | ||
|
|
||
| ## Step 3 — Share with data consumers and implementers to review and align on implementation | ||
|
|
||
| This is a working session, not just a sign-off. With the analytics owner who'll consume the data and the engineering DRI who'll implement it: | ||
|
|
||
| - **Sanity-check the source-specific property behavior** — does it match what the source can actually send? | ||
| - **Decide which sources will implement what events, when.** Use this conversation to lock the implementation slices. | ||
| - **Slice the work if it won't land at once.** If a source's implementation will roll out in stages, push a subset of changes from this branch into smaller implementation branches using [push and pull between branches](https://www.avo.app/docs/data-design/branches/pulling-pushing-items-between-branches#pushing-items-to-another-branch). Each implementation branch can then move on its own timeline. | ||
|
|
||
| Required reviewers can be configured per source so the right people are pulled in automatically — see [Required reviewers](https://www.avo.app/docs/data-design/required-reviewers). <!-- REVIEW: confirm canonical URL for required reviewers --> | ||
|
|
||
| ## Step 4 — Implement and validate | ||
|
|
||
| Once the branch (or implementation slice) is aligned and approved: | ||
|
|
||
| - Engineering pulls the latest [Avo Codegen](https://www.avo.app/docs/implementation/avo-codegen-overview) for the source and uses the generated tracking functions. | ||
| - Validate in dev and staging using the inline debugger <!-- REVIEW: add link to inline debugger doc once URL is confirmed --> and the [Avo Inspector debugger](https://www.avo.app/docs/inspector/avo-inspector-overview). | ||
| - Once green in dev/staging, the branch is ready to merge. | ||
|
|
||
| **Dependency:** Codegen and Inspector must be set up on the source first. If they aren't yet, prioritize that before starting implementation. | ||
|
|
||
| ## Step 5 — Publish | ||
|
|
||
| Publish each Avo branch to main once the corresponding git branch is merged. If you're using direct publishing destinations (e.g. a webhook, cloud storage such as S3 or GCS, or a destination connector), confirm the publish completes after the merge. | ||
|
|
||
| If you broke the work into multiple implementation branches, repeat steps 3–5 for each. | ||
|
|
||
| ## Common pitfalls | ||
|
|
||
| - **Assigning a source to every event by default.** Saves time today, costs accuracy forever. Be deliberate. | ||
| - **Treating source-specific overrides as the rule, not the exception.** If you have many overrides on one source, the global definition is probably wrong. | ||
| - **Merging to main before implementation lands.** Inspector will report drift between plan and production until the code catches up. Keep the branch open until the slice is implemented. | ||
| - **Skipping push/pull and copying work manually between branches.** Manual copies drift. Use push to keep the source of truth on one branch. | ||
|
|
||
| ## Related docs | ||
|
|
||
| - [Start data design](https://www.avo.app/docs/data-design/start-data-design) — for greenfield tracking plans. | ||
| - [Define sources and destinations](https://www.avo.app/docs/data-design/avo-tracking-plan/define-sources-and-destinations) — full source configuration reference. | ||
| - [Configuring when properties are required or optional](https://www.avo.app/docs/data-design/avo-tracking-plan/properties#configuring-when-properties-are-required-or-optional) — property behavior reference. | ||
| - [Push and pull between branches](https://www.avo.app/docs/data-design/branches/pulling-pushing-items-between-branches#pushing-items-to-another-branch) — move work between branches without merging. | ||
| - [Avo Codegen overview](https://www.avo.app/docs/implementation/avo-codegen-overview) — generate type-safe tracking calls per source. | ||
| - [Avo Inspector overview](https://www.avo.app/docs/inspector/avo-inspector-overview) — validate implementation in dev, staging, and production. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Use relative internal links instead of absolute https://www.avo.app/docs/... URLs.
Every internal cross-reference in this guide (Steps 1-5, intro, related docs) uses a full absolute URL to the production site. The existing convention in this docs repo is to use relative paths, as seen in define-sources-and-destinations.mdx, e.g. "how to set up Inspector](/data-design/start-using-inspector)" and "you want to generate the code in](/implementation/supported-programming-languages)". Hardcoded absolute URLs will drift from relative links if the site's base path or domain changes, and are inconsistent with the rest of the docs.
♻️ Example fix pattern
- [Define sources and destinations](https://www.avo.app/docs/data-design/avo-tracking-plan/define-sources-and-destinations)
+ [Define sources and destinations](/data-design/avo-tracking-plan/define-sources-and-destinations)🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@pages/data-design/guides/Onboarding` new sources around lines 29 - 116,
Replace the hardcoded production-domain links in this guide with the repo’s
relative internal link style throughout the intro, Steps 1-5, and Related docs.
Use the same path-based references as other docs files like
define-sources-and-destinations.mdx, updating each Avo workflow, Codegen,
Inspector, branches, and source/destination reference link to relative paths
instead of absolute https://www.avo.app/docs/... URLs.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary by CodeRabbit