Add directory structure explainer #66
Conversation
|
Learn Build status updates of commit 1d69fbc: ✅ Validation status: passed
For more details, please refer to the build report. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 issues. Other issues are also a high priority. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
| At the root of packages.microsoft.com, you’ll see folders like: | ||
|
|
||
| - `/config/<distro>/<version>/prod.list`: Contains repo configuration files for each supported distribution. | ||
| - `/repos/`: Contains product-specific repositories (for example, edge, azure-cli, microsoft-prod). |
There was a problem hiding this comment.
Technically, /repos/ contains all the apt repos including ones that aren't product specific. Like there's https://packages.microsoft.com/repos/microsoft-ubuntu-noble-prod/ which is also available at https://packages.microsoft.com/ubuntu/24.04/prod/.
But /repos/ is indeed the only way to access product-specific apt repos so I think this statement is fine as long as you point out that it's only for apt repos.
I'd also recommend adding an item here to say there's also /yumrepos/ for yum repos.
|
|
||
| - `/config/<distro>/<version>/prod.list`: Contains repo configuration files for each supported distribution. | ||
| - `/repos/`: Contains product-specific repositories (for example, edge, azure-cli, microsoft-prod). | ||
| - `/ubuntu/`: Contains distribution-specific repos for Microsoft packages that integrate with Ubuntu’s APT system. |
There was a problem hiding this comment.
Maybe changing this to:
/<distro>/(e.g. /ubuntu/): Contains distribution-specific repos for Microsoft packages
| - The packages.microsoft.com repository is public and designed for programmatic consumption by package managers, not for manual browsing, though directory listing is enabled for convenience. | ||
| - The repos tree is product-centric, not distribution-centric. For example: `repos/edge/`, `repos/azure-cli/`, repos/microsoft-prod/', etc. Each contains metadata for multiple distributions, so the same product repo can serve Ubuntu, Debian, etc. | ||
| - This differs from Ubuntu’s pool/main structure, which is strictly tied to Debian policy and archive layout.Ubuntu’s main pool is controlled by Canonical and only includes open-source or vetted packages, so proprietary software, such as Microsoft Edge, cannot be included there. This separation ensures Microsoft is able to directly provide updates and signing keys, as well as compliance with licensing (Microsoft Edge is closed-source). It also enables faster delivery of new versions without waiting for Ubuntu’s release cycle. | ||
| - Microsoft uses a centralized model rather than duplicating packages under each `distro` folder. This avoids redundancy and simplifies publishing across multiple Linux distributions. |
There was a problem hiding this comment.
I'm not totally sure I understand what this means? Teams at Microsoft can and do publish different packages for different distros and distro versions.
There was a problem hiding this comment.
I guess this is maybe meant to refer to repos under /repos/ and /yumrepos/?
| - The repos tree is product-centric, not distribution-centric. For example: `repos/edge/`, `repos/azure-cli/`, repos/microsoft-prod/', etc. Each contains metadata for multiple distributions, so the same product repo can serve Ubuntu, Debian, etc. | ||
| - This differs from Ubuntu’s pool/main structure, which is strictly tied to Debian policy and archive layout.Ubuntu’s main pool is controlled by Canonical and only includes open-source or vetted packages, so proprietary software, such as Microsoft Edge, cannot be included there. This separation ensures Microsoft is able to directly provide updates and signing keys, as well as compliance with licensing (Microsoft Edge is closed-source). It also enables faster delivery of new versions without waiting for Ubuntu’s release cycle. | ||
| - Microsoft uses a centralized model rather than duplicating packages under each `distro` folder. This avoids redundancy and simplifies publishing across multiple Linux distributions. | ||
| - When you install the Microsoft repo config (packages-microsoft-prod.deb), it adds the correct deb `[arch=amd64] https://packages.microsoft.com/repos/edge` stable main line for your Linux distribution. APT then uses Microsoft’s metadata (Release, Packages.gz) to resolve dependencies. The actual `.deb` files live under `repos/edge/pool/main/...`, but you should never hardcode those paths because the APT package manager handles it. |
There was a problem hiding this comment.
Instead of saying that the repo config packages adds a line..., I would just say that the deb package adds a .list file to /etc/apt/sources.list.d/ for the repository.
Also, a couple things here that might be worth mentioning:
- For yum repos, we provide packages-microsoft-prod.rpm packages similar to packages-microsoft-prod.deb
- Each repo config package provides the repo signing key
There was a problem hiding this comment.
For yum repos, the .list file equivalent would be a .repo file. You can a few here:
sdherr
left a comment
sdherr
left a comment
There was a problem hiding this comment.
Some suggestions, line-by-line. Overall I think this is a good clarifying update but just want to improve the accuracy a bit. We also have a little bit of similar documentation in the Readme of the linux-package-repositories repo, but I 100% support updating the docs here.
https://github.com/microsoft/linux-package-repositories?tab=readme-ov-file#configuring-the-repository-on-your-linux-system
|
|
||
| At the root of packages.microsoft.com, you’ll see folders like: | ||
|
|
||
| - `/config/<distro>/<version>/prod.list`: Contains repo configuration files for each supported distribution. |
There was a problem hiding this comment.
/config/<distro>/<version>/packages-microsoft-prod.[rpm|deb]: Provides the.listor.repofile to enable the distribution-specific repository for each system, as well as the appropriate signing key. If more a manual or non-default (for example, enabling the early-access not-yet-production "insiders" repos) approach is desired then individual.listor.repofiles are available in this directory.
| At the root of packages.microsoft.com, you’ll see folders like: | ||
|
|
||
| - `/config/<distro>/<version>/prod.list`: Contains repo configuration files for each supported distribution. | ||
| - `/repos/`: Contains product-specific repositories (for example, edge, azure-cli, microsoft-prod). |
There was a problem hiding this comment.
/repos/: Contains all.deb-based repos, including product-specific repos that are designed to work with all deb-based distributions, likeedgeorazure-cli. See individual product documentation for the preferred installation instructions./yumrepos/: Contains all.rpm-based repos, including product-specific repos that are designed to work with all rpm-based distributions, likeedgeorazure-cli. See individual product documentation for the preferred installation instructions.
|
|
||
| - `/config/<distro>/<version>/prod.list`: Contains repo configuration files for each supported distribution. | ||
| - `/repos/`: Contains product-specific repositories (for example, edge, azure-cli, microsoft-prod). | ||
| - `/ubuntu/`: Contains distribution-specific repos for Microsoft packages that integrate with Ubuntu’s APT system. |
There was a problem hiding this comment.
/<distro>/<version>/: Contains distribution-specific repos for Microsoft packages that are built for a particular distribution-version. These are all symlinks / copies of some repositories that can also be found under/repos/or/yumrepos/, but surfaced at the top level too for convenience.
| A few things to keep in mind regarding the packages.microsoft.com repo structure: | ||
|
|
||
| - The packages.microsoft.com repository is public and designed for programmatic consumption by package managers, not for manual browsing, though directory listing is enabled for convenience. | ||
| - The repos tree is product-centric, not distribution-centric. For example: `repos/edge/`, `repos/azure-cli/`, repos/microsoft-prod/', etc. Each contains metadata for multiple distributions, so the same product repo can serve Ubuntu, Debian, etc. |
There was a problem hiding this comment.
- Some repos are product-centric, not distribution-centric. ... See individual product documentation for the preferred installation instructions.
| - The packages.microsoft.com repository is public and designed for programmatic consumption by package managers, not for manual browsing, though directory listing is enabled for convenience. | ||
| - The repos tree is product-centric, not distribution-centric. For example: `repos/edge/`, `repos/azure-cli/`, repos/microsoft-prod/', etc. Each contains metadata for multiple distributions, so the same product repo can serve Ubuntu, Debian, etc. | ||
| - This differs from Ubuntu’s pool/main structure, which is strictly tied to Debian policy and archive layout.Ubuntu’s main pool is controlled by Canonical and only includes open-source or vetted packages, so proprietary software, such as Microsoft Edge, cannot be included there. This separation ensures Microsoft is able to directly provide updates and signing keys, as well as compliance with licensing (Microsoft Edge is closed-source). It also enables faster delivery of new versions without waiting for Ubuntu’s release cycle. | ||
| - Microsoft uses a centralized model rather than duplicating packages under each `distro` folder. This avoids redundancy and simplifies publishing across multiple Linux distributions. |
| - The repos tree is product-centric, not distribution-centric. For example: `repos/edge/`, `repos/azure-cli/`, repos/microsoft-prod/', etc. Each contains metadata for multiple distributions, so the same product repo can serve Ubuntu, Debian, etc. | ||
| - This differs from Ubuntu’s pool/main structure, which is strictly tied to Debian policy and archive layout.Ubuntu’s main pool is controlled by Canonical and only includes open-source or vetted packages, so proprietary software, such as Microsoft Edge, cannot be included there. This separation ensures Microsoft is able to directly provide updates and signing keys, as well as compliance with licensing (Microsoft Edge is closed-source). It also enables faster delivery of new versions without waiting for Ubuntu’s release cycle. | ||
| - Microsoft uses a centralized model rather than duplicating packages under each `distro` folder. This avoids redundancy and simplifies publishing across multiple Linux distributions. | ||
| - When you install the Microsoft repo config (packages-microsoft-prod.deb), it adds the correct deb `[arch=amd64] https://packages.microsoft.com/repos/edge` stable main line for your Linux distribution. APT then uses Microsoft’s metadata (Release, Packages.gz) to resolve dependencies. The actual `.deb` files live under `repos/edge/pool/main/...`, but you should never hardcode those paths because the APT package manager handles it. |
There was a problem hiding this comment.
edge is a poor choice of repo to use as an example here, because we actually don't have a .deb that installs the edge repo. Maybe use the ubuntu repo as an example instead.
No description provided.