Skip to content

Clarify package installation and document retired package repositories - #78

Merged
guanzhousongmicrosoft merged 4 commits into
documentdb:mainfrom
GuanzhouSong:dev/guanzhousong/retired-package-repo-cleanup
Sep 10, 2026
Merged

Clarify package installation and document retired package repositories#78
guanzhousongmicrosoft merged 4 commits into
documentdb:mainfrom
GuanzhouSong:dev/guanzhousong/retired-package-repo-cleanup

Conversation

@GuanzhouSong

@GuanzhouSong GuanzhouSong commented Sep 10, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Restructure getting-started/prebuilt-packages.md to lead with the stand-alone setup wizard, and separately document component-level PostgreSQL + gateway workflows, PGDG extension packages, and community/source builds, keeping release-asset installation as reference material
  • Record that the package withdrawal also pulled the older PostgreSQL 16 extension packages from the Ubuntu 24.04 and RHEL-compatible 9 repositories
  • Explain the empty signed metadata parked at the retired repository URLs, and give the APT/DNF repository cleanup commands
  • Name the three packaging entry points so a community build of an unhosted target does not require reading the packaging tree first
  • Correct the VS Code quick start's sample data, which still described the 0.116 dataset
  • Fix grammar, jargon (spell out "major" as "major version" throughout, use consistent v0.117 prefixing), and other small wording issues

Context

The 0.117 page already states that other targets are outside the hosted package matrix, that older packages are not retained, and that existing installations keep running without updates. It stopped short of what an operator on a retired target actually has to do, and nothing in this repo documented the repository cleanup. It also buried the recommended stand-alone install path behind the release-asset instructions, so this restructures the page to lead with it.

The VS Code quick start described a sampledb database with users, products, orders and analytics collections. That is the v0.116-0 dataset — documentdb-local/sample-data/ held 01-users.js through 04-analytics.js, each seeding sampledb. v0.117-0 replaces all four with 01-store-data.js plus two gzipped Extended JSON exports, seeding StoreData with 41,505 stores documents and 2 ratings documents. The extension ships no dataset of its own — QuickStartService runs the image's own init_documentdb_data.sh against its bundled sample-data directory — and the wizard defaults to the latest tag, so a reader following that page today got none of the four collections it named.

This supersedes #73, which was written against the 0.116 wording that #74 has since rewritten. The parts of #73 that #74 absorbed independently are dropped here, and the v0.117-0 packaging link already on main is kept rather than reintroducing the v0.116-0 one. #73 can be closed.

Validation

  • The retired-repository behavior and cleanup commands match the live guidance in PACKAGE-INSTALL.md on documentdb.github.io, shipped in Align website with the v0.116 package matrix documentdb.github.io#164 and still current after the 0.117 pass in #177
  • The three packaging entry points verified in the source repository: packaging/build_packages.sh (extension), packaging/gateway/build_gateway_packages.sh (gateway), and packaging/build_extra_packages.sh (common, tools, stand-alone, meta)
  • packaging/build_packages.sh still accepts deb11/deb12/deb13/ubuntu22.04/rhel8 and PostgreSQL 15-18, so the build-on-demand path for unhosted targets remains real
  • Sample data verified by diffing documentdb-local/sample-data/ between v0.116-0 and v0.117-0, against documentdb-local/sample-data/README.md at v0.117-0, and against microsoft/vscode-documentdb at 013e429f
  • Reviewed rendered Markdown for broken links/anchors after the restructure

@guanzhousongmicrosoft
guanzhousongmicrosoft force-pushed the dev/guanzhousong/retired-package-repo-cleanup branch from 98d04ef to 838027e Compare September 10, 2026 16:21
@GuanzhouSong GuanzhouSong changed the title Document the retired package repositories and their cleanup Clarify package installation and document retired package repositories Sep 10, 2026
The 0.117 page already states that other targets are outside the hosted
package matrix and that older packages are not retained, but it stops
short of what an operator on a retired target actually has to do.

Record that the withdrawal also pulled the older PostgreSQL 16 extension
packages from the Ubuntu 24.04 and RHEL-compatible 9 repositories, that
empty signed metadata is deliberately parked at the retired repository
URLs so package-manager refreshes keep working, and how to remove the
repository configuration. Name the three packaging entry points so a
community build of an unhosted target does not require reading the
packaging tree first.

Verified against the live documentdb.io package guidance and against
packaging/build_packages.sh, packaging/gateway/build_gateway_packages.sh
and packaging/build_extra_packages.sh in the source repository.

Claude-Session: https://claude.ai/code/session_01Bg344Sg5hCgoxD6aPsbp5b
Lead with stand-alone setup and explain component-level PostgreSQL and gateway workflows. Document PGDG and source builds, with release assets and retired-target guidance kept as reference.

Copilot-Session: e7d486f5-141c-47f0-ad9e-8bce20fdb52f
Signed-off-by: Guanzhou Song <guanzhou.song@gmail.com>
@GuanzhouSong
GuanzhouSong force-pushed the dev/guanzhousong/retired-package-repo-cleanup branch from 838027e to 8ab8ad6 Compare September 10, 2026 16:24
The page described a `sampledb` database with `users`, `products`,
`orders` and `analytics` collections. That is the v0.116-0 dataset:
documentdb-local/sample-data/ held 01-users.js, 02-products.js,
03-orders.js and 04-analytics.js, each seeding `sampledb`.

v0.117-0 replaces all four with 01-store-data.js plus two gzipped
Extended JSON exports, seeding a `StoreData` database with 41,505
`stores` documents and 2 `ratings` documents.

The extension ships no dataset of its own -- QuickStartService runs the
image's own /home/documentdb/gateway/scripts/init_documentdb_data.sh
against its /home/documentdb/gateway/sample-data directory -- and the
wizard defaults to the `latest` tag, so a reader following this page
today gets StoreData and none of the four collections named here.

Describe what the image actually seeds, point at the sample-data section
of the DocumentDB Local page for the detail, and keep the `sampledb`
name for anyone deliberately pinning a pre-0.117 tag.

Verified against v0.116-0 and v0.117-0 in documentdb/documentdb, and
against microsoft/vscode-documentdb at 013e429f.
@GuanzhouSong
GuanzhouSong force-pushed the dev/guanzhousong/retired-package-repo-cleanup branch from e810193 to 08f994f Compare September 10, 2026 16:30
@guanzhousongmicrosoft
guanzhousongmicrosoft merged commit 8c80d52 into documentdb:main Sep 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants