docs: add description about our code structure #26394
Conversation
openshift-ci
bot
added
release-note-none
do-not-merge/work-in-progress
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: Luap99 The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
openshift-ci
bot
added
the
approved
|
|
||
| #### pkg/machine/ | ||
|
|
||
| - core code for podman machine commands |
| - core code for podman machine commands | ||
|
|
||
| ### test/ | ||
|
|
There was a problem hiding this comment.
i think @ninja-quokka had some initial trouble understanding these subdirectories. I would be fine with merging this PR without them but maybe that's something we can do soon thereafter? @ninja-quokka im kind of thinking you would be a good candidate for that?
There was a problem hiding this comment.
Yeah I can post a follow up PR with a small addition about the test directory structure. I should really add more content to podman/test/apiv2/README.md before my ideas get oom_reaper'd
|
|
||
| Description about important directories in our repository. | ||
|
|
||
| ### cmd/ |
|
i like this pr |
|
|
||
| - various packages to do all sorts of different things | ||
|
|
||
| #### pkg/api/ |
There was a problem hiding this comment.
Maybe ##### pkg/api/handlers/compat and ##### pkg/api/handlers/libpod.
There was a problem hiding this comment.
I guess I’ll just raise the topic:
Should we change some of the paths instead of documenting them?
pkg/domain/infra/abi→pkg/engine/localpkg/domain/infra/tunnel→pkg/engine/remotepkg/bindings→pkg/remote/clientpkg/api/handlers→pkg/remote/server
or something vaguely like that?
There’s never a good time to make these changes (and, ugh, we would need to have a naming discussion), but just about every time I’m working on Podman, I wish they had already happened, and after a few years of this wish, it gets old.
(Do we have a stable API commitment / external consumers that mean that we can’t, or shouldn’t, rename the packages?)
… these are not exclusive, a renaming discussion, if any, is not really a reason to block the PR. |
Document most important directories when trying to understand our project. Signed-off-by: Paul Holzinger <[email protected]>
|
[NON-BLOCKING] Packit jobs failed. @containers/packit-build please check. Everyone else, feel free to ignore. |
There was a problem hiding this comment.
As a new contributor, a document like this would have saved @baude a few hours so +1 and thank you!
Added some thoughts.
There was a problem hiding this comment.
I agree the content serves the purpose of the PR of a "getting started guide for new folks"
Before merging a few small grammatical issues should be resolved:
- Capitalise proper nouns like Podman, Sphinx, SQLite, BoltDB.
- Capitalise the first letter in each of the dot points.
- Add periods to the end of each dot point.
| - directory created with "go mod vendor" | ||
| - this includes all go deps in our repo, DO NOT edit this directory directly, changes in dependencies must be made in their respective upstream repositories and then updated in go.mod | ||
|
|
||
| #### bin/ |
There was a problem hiding this comment.
nit: Should this be added to the top to keep the order?
|
|
||
| #### cmd/podman/ | ||
|
|
||
| - podman cli code, cli commands and flags are defined here, we are using github.com/spf13/cobra as library for command line parsing |
There was a problem hiding this comment.
| - podman cli code, cli commands and flags are defined here, we are using github.com/spf13/cobra as library for command line parsing | |
| - Podman CLI code, CLI commands and flags are defined here, we are using the [Cobra CLI library](https://github.com/spf13/cobra) for command line parsing. |
|
|
||
| ### docs/ | ||
|
|
||
| - sphinx based documentation for podman that is build on readthedocs (docs.podman.io) |
There was a problem hiding this comment.
| - sphinx based documentation for podman that is build on readthedocs (docs.podman.io) | |
| - Sphinx based documentation for Podman that is build on [Read the Docs](https://readthedocs.com/) and hosted at [docs.podman.io](https://docs.podman.io/en/latest/) |
| - underlying core for most podman operations, defines container, pod, volume management opartions | ||
| - contains the database to store these information on disk, either sqlite or botldb (our old db format) | ||
| - integrates with our other libraries such as: | ||
| - containers/storage create and mount container storage |
There was a problem hiding this comment.
nit: Do we want to use 4 indents here? If so please ignore.
|
|
||
| - CI scripts, packaging files some container image build files | ||
|
|
||
| ### docs/ |
There was a problem hiding this comment.
Maybe also link to docs/REAME.md in this section? It goes into more depth on the directory structure for docs/
| - core code for podman machine commands | ||
|
|
||
| ### test/ | ||
|
|
There was a problem hiding this comment.
Yeah I can post a follow up PR with a small addition about the test directory structure. I should really add more content to podman/test/apiv2/README.md before my ideas get oom_reaper'd
Document most important directories when trying to understand our project.
Comments welcome, this is mostly meant as quick getting started guide for new folks trying to understand the codebase.
Does this PR introduce a user-facing change?