I think we consciously made a decision to move to/stick to fedpkgin the docs here because these are meant to be Fedora specific, and so are intended to be used by people looking to become package maintainers.

With the rpmbuild etc., steps, folks spent all the time learning those tools, only then to be moved on to the fedpkg based workflow later. That was quite confusing it itself, especially given that one has to use a scm repo later but not with rpmbuild and all that.

When packaging, as long as one uses a git repository, everything fedpkg will (should) work---at least the bits that are required for building the package: mockbuild, lint; and then it's a more natural progression to go request-branch etc. (in my book).

Another thing is the usage of rpmautospec, which works well with fedpkg (although to keep the history from the review, one has to go about a bit of a rebase path: #56 )

I'm sure there'll be personal preferences here. Some folks probably prefer using rpmbuild when packaging, others like to do everything with fedpkg. I think I'd prefer everything to be fedpkg in our package maintainer docs because once one gets to the stage of having a package approved, they have to move to fedpkg anyway---so I'd rather they get used to fedpkg from the start.

Folks looking to learn general package building with rpm should look at the rpm docs which should be distro agnostic?

I understand that "consistency" is a reason why you want to do that. But fedpkg just doesn't work right outside dist-git repos, and it's broken in subtle and non-obvious ways (for example, why you need to pass --release f36 or not). Every "experienced" packager I've talked with agrees that using fedpkg for non-dist-git packages is wrong / broken. And I don't think giving new packagers advice that "experienced" packagers will tell them is broken is a good idea.

If you want to advocate for consistency, I'd rather recommend packagers to set up their local RPM environment with an .rpmmacros file like this:

%_topdir        %(pwd)
%_rpmtopdir     %{_topdir}
%_builddir      %{_rpmtopdir}
%_buildrootdir  %{_rpmtopdir}
%_sourcedir     %{_rpmtopdir}
%_specdir       %{_rpmtopdir}
%_rpmdir        %{_rpmtopdir}
%_srcrpmdir     %{_rpmtopdir}

So rpmbuild and spectool will behave consistently with what fedpkg will do later on.

Hrm, why don't we advocate that people use dist-git from the beginning? Create a git repo and do all their work in there---and then there's no difference between them preparing a package and then maintaining it later? They also don't need to understand the difference between rpmbuild and then mock, and then a new tool called fedpkg because fedpkg abstracts over all of this, and they don't need to pollute their systems with all the build-requires etc. either.

I had brought this up on the list, and it was discussed in some detail:

https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/thread/FT3PZP4OACQQ5NZXP7ZPNZV57J7OEXOC/#LOK3CBTKV4V2RVUVYRTJDA4OTYXU6E25

I was against fedpkg (I'm not too happy with folks having to use it from the start either), but you'll see from the thread that there are other issues with having newcomers configure their systems from the start etc. I even opened a PR to make the config you've noted above as default:

https://pagure.io/rpmdevtools/pull-request/48

Over time, I've moved to using the dist-git way of doing things. In the recent outreachy round, I had ~5 complete newcomers with very limited programming experience and they were all able to package (and get sponsored) using a git repo right from the beginning. So I can't say if it works for everyone, but in my experience, using fedpkg right from the start did not make it harder for new-comers.

Edit: I continue to worry about people "knowing how to use fedpkg" without knowing how things work in detail, but that seems to be a constant struggle with people moving to IDEs etc. without really knowing what's happening under the hood. I don't have an answer here---all I can say is that using fedpkg helped newcomers make and maintain packages, and I hope that over time they'll figure out more rpm details as they go along

Hrm, why don't we advocate that people use dist-git from the beginning? Create a git repo and do all their work in there---and then there's no difference between them preparing a package and then maintaining it later?

Because a git repo and dist-git are not the same thing. dist-git is the combination of "git repo" and "sources" file and a few other things. You can't use that workflow with a "normal" git repo, because you don't have a lookaside cache, among other things.

They also don't need to understand the difference between rpmbuild and then mock, and then a new tool called fedpkg because fedpkg abstracts over all of this, and they don't need to pollute their systems with all the build-requires etc. either.

No, you misunderstand me. I don't advocate for building RPM packages without mock (i.e. with rpmbuild -bb or rpmbuild -ba). That's bad, and people should be using mock for this. But there's another step between creating a spec file and building it in mock: building the SRPM file. And that works just fine with rpmbuild -bs, without needing fedpkg or using weird mock features:

1) edit foo.spec file
2) build SRPM with rpmbuild -bs foo.spec
3) build packages with mock *.src.rpm

And with dist-git, you can optionally use fedpkg to abstract over steps 2 and 3:

1) edit foo.spec file
2) build SRPM with rpmbuild -bs foo.spec orfedpkg srpm --release $release
3) build packages with mock -r fedora-$release-x86_64 *.src.rpm or fedpkg mockbuild --release $release

Additionally, there's the problem that fedpkg mockbuild doesn't pass through all its command line arguments to mock. So if you want to add some flag to mock, you'll need to fall back to calling it directly, anyway.

I understand the complaint, fedpkg really is intended to be used with dist-git.

However, in my view, this tutorial is intended to be about packaging for Fedora.
Many different workflows can, and have been, be created.
One of them needs to be chosen for a tutorial.
"fedpkg for all rpm tasks" was the choice that has been made here.
I feel that it is the correct choice,
because it is fedpkg powerful enough to handle all the tasks that a new packager needs to do,
and provides a single interface to all of them,
without needing manual configuration.

I already almost included doing everything inside a local Git repository.
This discussion makes it even more clear that it is the right thing to do.
Sure, a local Git repository with correctly named branches is not the same as a full dist-git repository.
But it is close to that,
and fedpkg's dependency to the lookaside cache is not as wide as you seem to imply.
Only commands that actually do something with the lookaside cache require it to be available,
the others work just fine without it.

A different approach could be to start by cloning a real dist-git repo.
GNU Hello is actually available and could be used.
But maybe that is a different tutorial,
as the rpm packaging part would just be "build it, it worked, done".
The useful part would be how to setup everything so that you can actually clone the repository.

My main worry about "fedpkg for all rpm tasks" was actually new package submission.
That is a major use case where a dist-git repository is not available.
I was much reassured by Ankur's success with the Outreachy participants.

I begin to understand that we have a fundamentally different point of view here.

Mine can be summarized as "fedpkg is not the correct tool here and it's not designed to do what you're doing with it", but yours seems to be "it works most of the time so it is the right thing to do".

But I would argue that you need something that works all of the time. Preferring consistency over correctness only works as long as people don't get hit by the exception to "it works most of the time", because then you're back to using the "correct" but "inconsistent" tool, anyway.

I agree that the tools we have here are not ideal, and the learning curve could be less steep. But this is what we have, and teaching people to use the "wrong" tools just because it will be easier to learn at first, but then much harder and more confusing when they bump against the problems inherent with that approach, is something that I will never agree with.

don't mind me, just cleaning up after myself