PR#101: Simplify scratch build instructions - fedora-docs/package-maintainer-docs

fedora-docs / package-maintainer-docs

#101 Simplify scratch build instructions

Closed a year ago by oturpe. Opened a year ago by oturpe.

fedora-docs/ oturpe/package-maintainer-docs fedpkg-srpm-instead-of-rpmbuild into main

Simplify scratch build instructions

Otto Liljalaakso • a year ago

4083c1b

modules/ROOT/pages/Package_Maintenance_Guide.adoc

file modified

+8 -6

		`@@ -91,14 +91,16 @@`
		`fedpkg srpm`
		`....`

		`- You can request a Koji _scratch build_`
		`- (a test build, which will not go to any repository)`
		`- of the generated .src.rpm`
		- with the `koji build --scratch` command (see `man koji`).
		`-`
		`=== Do a scratch build using Koji`
		`+ ....`
		`+ fedpkg scratch-build --srpm`
		`+ ....`

		`- See xref:Using_the_Koji_Build_System#scratch_builds[Koji scratch builds].`
		`+ This builds the package against the buildroot in the Koji buildsystem,`
		`+ without actually including it in the release.`
		`+ This kind of test build is more effective in revealing problems than a local Mock build,`
		`+ because it covers all officially supported architectures`
		`+ and builds against Koji's buildroot rather than a release repository.`

		`=== Check changes you have made`
		`....`

modules/ROOT/pages/Using_the_Koji_Build_System.adoc

file modified

-49

		`@@ -91,55 +91,6 @@`
		`following builds are canceled,`
		`but the builds that already succeeded are pushed to the repository.`

		`- [#scratch_builds]`
		`- === Scratch Builds`
		`-`
		`- Sometimes it is useful to be able to build a package against the buildroot`
		`- without actually including it in the release.`
		`- This is called a scratch build.`
		`-`
		`- The following section covers using koji directly,`
		`- as well as the fedpkg tool,`
		`- to do scratch builds.`
		`-`
		`- To create a scratch build from changes you haven't committed, do the following:`
		`-`
		`- ....`
		`- fedpkg scratch-build --srpm`
		`- ....`
		`-`
		`- From the latest git commit:`
		`-`
		`- ....`
		`- koji build --scratch rawhide 'git url'`
		`- ....`
		`-`
		`- If you have committed the changes to git`
		`- and you are in the current branch,`
		- you can do a scratch build with `fedpkg`,
		`- which wraps the koji command line tool with the appropriate options:`
		`-`
		`- ....`
		`- fedpkg scratch-build`
		`- ....`
		`-`
		`- To run a scratch build for a specific architecture:`
		`-`
		`- ....`
		`- fedpkg scratch-build --arches <archs>`
		`- ....`
		`-`
		- `<archs>`can be a comma separated list of several architectures.
		`-`
		`- Finally, it is possible to combine the scratch-build command`
		`- with a specific koji tag in the form:`
		`-`
		`- ....`
		`- fedpkg scratch-build --target TARGET`
		`- ....`
		`-`
		- Run `fedpkg scratch-build --help` or `koji build --help` for more information.
		`-`
		`[#build_failures]`
		`=== Build Failures`

oturpe commented a year ago

Page "Using the Koji Build System" had a section about Koji scratch builds, listing various way of doing them using 'koji' and 'fedpkg'. This listing was not specifically useful, because:

It was not comprehensive, i.e. it just enumerated possible arguments, but did not cover all of them.
It did not have a clear position if koji or fedpkg should be preferred, and similarly for 'fedpkg build --scratch' and 'fedpkg scratch-build'.
It did not differentiate between rare needs like building against defined Koji target or doing a scratch build from a pushed dist-git commit, and the common need of building from local changes.
It suggested calling 'rpmbuild' directly, without anything in these docs explaining how to configure it correctly.

Actually, only the most common case is worth documenting like this, and it should be in "Package Maintenance Guide". Such simplification is done here, by erasing the whole section and documenting 'fedpkg scratch-build --srpm' in the Guide.

churchyard commented a year ago

On a related note, should we recommend fedpkg build --scratch --srpm instead?

qulogic commented a year ago

I was going to suggest fedpkg scratch-build --srpm for both lines.

oturpe commented a year ago

Good suggestions, worth following.
However, a bit more work ensues,
because the surrounding prose and commands makes even less sense after that change.

I will rewrite this section to always use fedpkg,
then just mention koji and the additional options it provides in the end.

rebased onto e1fc47d7151c99e11c3ebda0b234bef9459f9a2c

a year ago

oturpe commented a year ago

Done.
The koji Git url form is actually explained separately later in the document,
so I removed it from the scratch builds section.
No need to explain the same thing twice.

churchyard commented on line 26 of modules/ROOT/pages/Using_the_Koji_Build_System.adoc a year ago

Assuming fedpkg scratch-build is the same as fedpkg build --scratch the commit actually needs to be pushed to a non-fork branch, not just committed.

zbyszek commented on line 13 of modules/ROOT/pages/Using_the_Koji_Build_System.adoc a year ago

"Koji-related" ?
"lower-level"

zbyszek commented a year ago

Assuming fedpkg scratch-build is the same as fedpkg build --scratch the commit actually needs to be pushed to a non-fork branch, not just committed.

I checked this now, and indeed, that's the case:

$ fedpkg scratch-build
Could not execute scratch_build: There are unpushed changes in your repo
Try option --srpm to make scratch build from local changes.

~~This is shitty.~~

I don't think it makes sense to push people towards this command then.
Instead, just replace the rpmbuild -bs with fedpkg srpm.

EDIT: Ah, I can't read.

fedpkg scratch-build --srpm works fine.

Edited a year ago by zbyszek

rebased onto fb1d1b628a63abc7bcba2de7edca4ddbdbe5ba06

a year ago

oturpe commented a year ago

Thank you taking some time to look into this!
Looking at this a bit more comprehensively,
I actually feel that the whole Scratch builds section is not providing much value here.
As soon as a packager discovers what scratch builds are,
they are better of typing fedpkg scratch-build --help or koji build --help
than reading such incomplete and arbitrary collection of commands.

So, I switched focus a little bit:
Everything except the most common case of fedpkg scratch-build --srpm can go,
and the common case can be moved to "Package Maintenance Guide",
where it fits better.

What do you think?

(I will push the two-line change to use fedpkg scratch-build --srpm separately now,
as that seems to be uncontroversial and was the original topic for this PR.)

rebased onto 4083c1b

a year ago

zbyszek commented a year ago

Hmm, I'm not convinced. It is true that those docs "duplicate" the in-built program help, but I think that they still provide value. The built-in docs are very terse, and not very well formatted, so many people prefer the web version, even if it is sometimes incomplete. Also the web version is indexed by the search engines and can be linked to. I think that a document titled "Using the Koji build system" should describe scratch builds.

oturpe commented a year ago

My line of thinking is that Package Maintainer Docs should not attempt to comprehensively document the tools.
Each individual tool should do that in their own docs,
and the Package Maintainer Docs should concentrate on how they are all tied together to create the Fedora packaging environment.
So listing all the different options of scratch builds should go to fedpkg or koji docs.
So I went to take a look and found this:
https://docs.pagure.org/koji/using_the_koji_build_system/?highlight=scratch+build#

It is basically the same article, but of course these two have diverged from each other.
These two should be merged somehow.
Until that happens, I do not see much value in improving this instance any more,
so I will close this pull request now.

Pull-Request has been closed by oturpe

a year ago