-
Notifications
You must be signed in to change notification settings - Fork 1
Update community repository for podman shared documentation #1
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
mohanboddu
wants to merge
2
commits into
podman-container-tools:main
Choose a base branch
from
mohanboddu:initial-docs
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| ## The Podman Project Community Code of Conduct | ||
|
|
||
| The Podman project follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md). |
Large diffs are not rendered by default.
Oops, something went wrong.
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,125 @@ | ||
| # Contributing to Podman Container Tools Projects: Go Language Guidelines | ||
|
|
||
| This is an appendix to the main [Contributing Guide](CONTRIBUTING.md) and is intended to be read after that document. | ||
| It contains guidelines and general rules for contributing to projects under the Podman Container Tools organization that are written in the Go language. | ||
| At present, this means the following repositories: | ||
|
|
||
| - [podman](https://github.com/podman-container-tools/podman) | ||
| - [buildah](https://github.com/podman-container-tools/buildah) | ||
| - [skopeo](https://github.com/podman-container-tools/skopeo) | ||
| - [container-libs](https://github.com/podman-container-tools/container-libs) | ||
|
|
||
| ## Topics | ||
|
|
||
| * [Unit Tests](#unit-tests) | ||
| * [Go Format and lint](#go-format-and-lint) | ||
| * [Go Dependency updates](#go-dependency-updates) | ||
| * [Testing changes in a dependent repository](#testing-changes-in-a-dependent-repository) | ||
| * [git bisect a change in a Go dependency](#git-bisect-a-change-in-a-go-dependency) | ||
|
|
||
| ## Unit Tests | ||
|
|
||
| Unit tests for Go code are added in a separate file within the same directory, named `..._test.go` (where the first part of the name is often the name of the file whose code is being tested). | ||
| Our Go projects do not require unit tests, but contributors are strongly encouraged to unit test any code that can have a reasonable unit test written. | ||
|
|
||
| ### Go Format and lint | ||
|
|
||
| We are using the [`gofumpt`](https://github.com/mvdan/gofumpt) formatter for our go code, you can either use it directly or format via `make fmt`. | ||
| For linting we use [`golangci-lint`](https://github.com/golangci/golangci-lint), use `make validate` to run it together with some other basic commit checks. | ||
|
|
||
| ## Go Dependency updates | ||
|
|
||
| To automatically keep dependencies up to date we use the [renovate](https://github.com/renovatebot/renovate) bot. | ||
| The bot automatically opens new PRs with updates that should be merged by maintainers. | ||
|
|
||
| However sometimes, especially during development, it can be the case that you like to update a dependency. | ||
|
|
||
| To do so you can use the `go get` command, for example to update the storage library to a specific version, use: | ||
| ``` | ||
| $ go get go.podman.io/storage@v1.60.0 | ||
| ``` | ||
|
|
||
| Or to update it to the latest commit from main use: | ||
| ``` | ||
| $ go get go.podman.io/storage@main | ||
| ``` | ||
|
|
||
| This command will update the go.mod/go.sum files, in some repos we use [go's vendor mechanism](https://go.dev/ref/mod#vendoring) | ||
| so there you must also update the files in the vendor dir. To do so use: | ||
| ``` | ||
| $ make vendor | ||
| ``` | ||
|
|
||
| If you are working in the [container-libs](https://github.com/podman-container-tools/container-libs) monorepo use: | ||
| ``` | ||
| make vendor | ||
| ``` | ||
| This command syncs the dependency versions across all modules in the repo. | ||
|
|
||
|
|
||
| Then commit the changes and open a PR. If you want to add other changes it is recommended to keep the | ||
| dependency updates in their own commit as this makes reviewing them much easier. | ||
|
|
||
| Note when cutting a new release always make sure we only use tagged version of our own podman-container-tools/... | ||
| dependencies to ensure all our tools use the same properly tested library versions. | ||
|
|
||
| ## Testing changes in a dependent repository | ||
|
|
||
| Sometimes it is helpful (or a maintainer asks for it) to test your library changes in the final binary, e.g. podman. | ||
|
|
||
| Assume we like to test a container-libs/common PR in Podman so that we can have the full CI tests run there. | ||
| First you need to push your container-libs/common changes to your github fork (if not already done). | ||
| Now open the podman repository, create a new branch there and then use. | ||
| ``` | ||
| $ go mod edit -replace go.podman.io/common=github.com/<account name>/<fork name>/common@<branch name> | ||
| ``` | ||
| Replace the variable with the correct values, in my case it the reference might be `github.com/Luap99/container-libs/common@myfeature`, where | ||
| - account name == `Luap99` | ||
| - fork name == `container-libs` | ||
| - branch name that I like to test == `myfeature` | ||
|
|
||
| Then just run the vendor command again. | ||
| ``` | ||
| $ make vendor | ||
| ``` | ||
|
|
||
| Now do any other changes that might be needed after the update and commit the changes then push them | ||
| to your Podman fork and open a new Podman PR, marking it as draft to make clear that this is a test | ||
| and should not be merged. This will trigger CI to run the tests. If everything passes the | ||
| podman-container-tools/container-libs PR did not introduce any regression which is a good. | ||
|
|
||
| Note: You generally do not have to test all your library changes like that. However if your changes | ||
| are big or break the API it might be a good idea to do this to avoid regression that need to be | ||
| fixed in follow ups or revert. | ||
|
|
||
| ## git bisect a change in a go dependency | ||
|
|
||
| If you performed a git bisect and the resulting commit is one that updated a library then most likely | ||
| the problem is in that library instead. In such cases it may be needed to find the bad commit from this | ||
| repository instead. Thankfully this is not much more difficult than the normal bisect usage. | ||
|
|
||
| Clone the library repository locally (for this example we assume it is github.com/podman-container-tools/container-libs) | ||
| which contains the storage library as module in a subdirectory, | ||
| I assume it is in a directory next to the podman repo. | ||
|
|
||
| Then in podman run (where you replace the path to the storage repo with your actual one) | ||
| ``` | ||
| $ go mod edit -replace go.podman.io/storage=/path/to/container-libs/storage | ||
| $ make vendor | ||
| ``` | ||
|
|
||
| Now the commit that was already found via the bisect in Podman should show you which storage version | ||
| was changed so you can then use them as good and bad version for the bisect in storage. | ||
|
|
||
| So use them in the storage repo for the `git bisect start BAD GOOD` command and then we need a bit | ||
| more work for the testing as we have to compile podman in the other repo and perform the check there. | ||
|
|
||
| The automated command can look like this: | ||
| ``` | ||
| $ git bisect run sh -c "cd /path/to/podman && make vendor && make podman && podman run $IMAGE someCommand || exit 1" | ||
| ``` | ||
|
|
||
| Compared to the normal bisect we basically just have to switch to the podman repo and then update | ||
| the vendor directory, as this will copy the local storage repo into that so the build after it | ||
| gets the current changes from the bisect commit. Given all works fine the result will point you | ||
| to a single commit in storage that caused the podman problem. | ||
Oops, something went wrong.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would add links to each topic in each project documentation. For example, you could add a link here on how to run integration tests in Podman. It could be something like: 'Here are useful links related to this topic for each project: