Skip to content

Commit 739eee5

Browse files
cgwalterscgwalters
committed
Rename HACKING -> CONTRIBUTING, add info about git + PRs
`CONTRIBUTING.md` is a friendlier and more common name. Explain the DCO bits in particular. Closes: #574 Signed-off-by: Colin Walters <[email protected]>
1 parent dad29ac commit 739eee5

File tree

3 files changed

+183
-117
lines changed

3 files changed

+183
-117
lines changed

‎CONTRIBUTING.md

Lines changed: 182 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,193 @@
1-
# Required dependencies
1+
# Contributing to bootc
22

3-
In order to build `bootc` you will need the following dependencies.
3+
Thanks for your interest in contributing! At the current time,
4+
bootc is implemented in Rust, and calls out to important components
5+
which are written in Go (e.g. https://github.com/containers/image)
6+
as well as C (e.g. https://github.com/ostreedev/ostree/). Depending
7+
on what area you want to work on, you'll need to be familiar with
8+
the relevant language.
49

5-
Fedora:
10+
There isn't a single approach to working on bootc; however
11+
the primary developers tend to use Linux host systems,
12+
and test in Linux VMs. One specifically recommended
13+
approach is to use [toolbox](https://github.com/containers/toolbox/)
14+
to create a containerized development environment
15+
(it's possible, though not necessary to create the toolbox
16+
dev environment using a bootc image as well).
17+
18+
At the current time most upstream developers use a Fedora derivative
19+
as a base, and the [hack/Containerfile](hack/Containerfile) defaults
20+
to Fedora. However, bootc itself is not intended to strongly tie to a particular
21+
OS or distribution, and patches to handle others are gratefully
22+
accepted!
23+
24+
## Key recommended ingredients:
25+
26+
- A development environment (toolbox or a host) with a Rust and C compiler, etc.
27+
While this isn't specific to bootc, you will find the experience of working on Rust
28+
is greatly aided with use of e.g. [rust-analyzer](https://github.com/rust-lang/rust-analyzer/).
29+
- An installation of [podman-bootc](https://github.com/containers/podman-bootc-cli)
30+
which note on Linux requires that you set up "podman machine". This document
31+
assumes you have the environment variable `CONTAINER_CONNECTION` set to your
32+
podman machine's name.
33+
34+
## Ensure you're familiar with a bootc system
35+
36+
Worth stating: before you start diving into the code you should understand using
37+
the system as a user and how it works. See the user documentation for that.
38+
39+
## Creating your edit-compile-debug cycle
40+
41+
Edit the source code; a simple thing to do is add e.g.
42+
`eprintln!("hello world);` into `run_from_opt` in [lib/src/cli.rs](lib/src/cli.rs).
43+
You can run `make` or `cargo build` to build that locally. However, a key
44+
next step is to get that binary into a bootc container image.
45+
46+
Use e.g. `podman build -t localhost/bootc -f hack/Containerfile .`.
47+
48+
From there, you can create and spawn a VM from that container image
49+
with your modified bootc code in exactly the same way as a systems operator
50+
would test their own bootc images:
51+
52+
```
53+
$ podman-bootc run localhost/bootc
54+
```
55+
56+
### Faster iteration cycles
57+
58+
You don't need to create a whole new VM for each change, of course.
59+
<https://github.com/containers/podman-bootc/pull/36> is an outstanding
60+
PR to add virtiofsd support, which would allow easily accessing the locally-built
61+
binaries. Another avenue we'll likely investigate is supporting podman-bootc
62+
accessing the container images which currently live in the podman-machine VM,
63+
or having a local registry which frontends the built container images.
64+
65+
A simple hack though (assuming your development environment is compatible
66+
with the target container host) is to just run a webserver on the host, e.g.
67+
`python3 -m http.server` or whatever, and then from the podman-bootc guest
68+
run `bootc usroverlay` once, and
69+
`curl -L -o /usr/bin/bootc http://10.0.1.2:8080/target/release/bootc && restorecon /usr/bin/bootc`.
70+
71+
### Debugging via lldb
72+
73+
The `hack/lldb` directory contains an example of how to use lldb to debug bootc code.
74+
`hack/lldb/deploy.sh` can be used to build and deploy a bootc VM in libvirt with an lldb-server
75+
running as a systemd service. Depending on your editor, you can then connect to the lldb server
76+
to use an interactive debugger, and set up the editor to build and push the new binary to the VM.
77+
`hack/lldb/dap-example-vim.lua` is an example for neovim.
78+
79+
The VM can be connected to via `ssh test@bootc-lldb` if you have [nss](https://libvirt.org/nss.html)
80+
enabled.
81+
82+
For some bootc install commands, it's simpler to run the lldb-server in a container, e.g.
683

784
```bash
8-
sudo dnf install clippy openssl-devel ostree-devel ostree-libs rustfmt
85+
sudo podman run --pid=host --network=host --privileged --security-opt label=type:unconfined_t -v /var/lib/containers:/var/lib/containers -v /dev:/dev -v .:/output localhost/bootc-lldb lldb-server platform --listen "*:1234" --server
86+
```
87+
88+
## Running the tests
89+
90+
First, you can run many unit tests with `cargo test`.
91+
92+
### container tests
93+
94+
There's a small set of tests which are designed to run inside a bootc container
95+
and are built into the default container image:
96+
97+
```
98+
$ podman run --rm -ti localhost/bootc bootc-integration-tests container
999
```
10100

11-
# Pre flight checks
101+
## Submitting a patch
12102

13-
Make sure you commented your code additions, then run
103+
The podman project has some [generic useful guidance](https://github.com/containers/podman/blob/main/CONTRIBUTING.md#submitting-pull-requests);
104+
like that project, a "Developer Certificate of Origin" is required.
105+
106+
### Sign your PRs
107+
108+
The sign-off is a line at the end of the explanation for the patch. Your
109+
signature certifies that you wrote the patch or otherwise have the right to pass
110+
it on as an open-source patch. The rules are simple: if you can certify
111+
the below (from [developercertificate.org](https://developercertificate.org/)):
112+
113+
```
114+
Developer Certificate of Origin
115+
Version 1.1
116+
117+
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
118+
660 York Street, Suite 102,
119+
San Francisco, CA 94110 USA
120+
121+
Everyone is permitted to copy and distribute verbatim copies of this
122+
license document, but changing it is not allowed.
123+
124+
Developer's Certificate of Origin 1.1
125+
126+
By making a contribution to this project, I certify that:
127+
128+
(a) The contribution was created in whole or in part by me and I
129+
have the right to submit it under the open source license
130+
indicated in the file; or
131+
132+
(b) The contribution is based upon previous work that, to the best
133+
of my knowledge, is covered under an appropriate open source
134+
license and I have the right under that license to submit that
135+
work with modifications, whether created in whole or in part
136+
by me, under the same open source license (unless I am
137+
permitted to submit under a different license), as indicated
138+
in the file; or
139+
140+
(c) The contribution was provided directly to me by some other
141+
person who certified (a), (b) or (c) and I have not modified
142+
it.
143+
144+
(d) I understand and agree that this project and the contribution
145+
are public and that a record of the contribution (including all
146+
personal information I submit with it, including my sign-off) is
147+
maintained indefinitely and may be redistributed consistent with
148+
this project or the open source license(s) involved.
149+
```
150+
151+
Then you just add a line to every git commit message:
152+
153+
Signed-off-by: Joe Smith <[email protected]>
154+
155+
Use your real name (sorry, no pseudonyms or anonymous contributions.)
156+
157+
If you set your `user.name` and `user.email` git configs, you can sign your
158+
commit automatically with `git commit -s`.
159+
160+
### Git commit style
161+
162+
Please look at `git log` and match the commit log style, which is very
163+
similar to the
164+
[Linux kernel](https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git).
165+
166+
You may use `Signed-off-by`, but we're not requiring it.
167+
168+
**General Commit Message Guidelines**:
169+
170+
1. Title
171+
- Specify the context or category of the changes e.g. `lib` for library changes, `docs` for document changes, `bin/<command-name>` for command changes, etc.
172+
- Begin the title with the first letter of the first word capitalized.
173+
- Aim for less than 50 characters, otherwise 72 characters max.
174+
- Do not end the title with a period.
175+
- Use an [imperative tone](https://en.wikipedia.org/wiki/Imperative_mood).
176+
2. Body
177+
- Separate the body with a blank line after the title.
178+
- Begin a paragraph with the first letter of the first word capitalized.
179+
- Each paragraph should be formatted within 72 characters.
180+
- Content should be about what was changed and why this change was made.
181+
- If your commit fixes an issue, the commit message should end with `Closes: #<number>`.
182+
183+
Commit Message example:
14184

15185
```bash
16-
cargo fmt
17-
cargo clippy
186+
<context>: Less than 50 characters for subject title
187+
188+
A paragraph of the body should be within 72 characters.
189+
190+
This paragraph is also less than 72 characters.
18191
```
19192

20-
Make sure to apply any relevant suggestions.
193+
For more information see [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)

‎HACKING.md

Lines changed: 0 additions & 107 deletions
This file was deleted.

‎README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,5 +31,5 @@ are also operating systems and distributions using bootc; here are some examples
3131

3232
## Developing bootc
3333

34-
Are you interested in working on bootc? Great! See our [HACKING.md](HACKING.md) guide.
34+
Are you interested in working on bootc? Great! See our [CONTRIBUTING.md](CONTRIBUTING.md) guide.
3535

0 commit comments

Comments
 (0)