Page MenuHomeFreeBSD

Convert most documentation about ports to git.
ClosedPublic

Authored by rene on Mar 27 2021, 9:12 PM.

Details

Summary

This also touches doc and src a bit. It should be committed per book or
article, not as one big change.

This includes:

  • Handbook (convert some examples about svn-ports to svn-src)
  • Porters Handbook
    • drop RCS IDs and SVN keywords
    • modernize some sections: CURRENT is now at 14 and iconv is in all supported versions of the base system.
    • the section about git status --short needs double-checking.
  • Committers Guide
    • drop psvn, addport, mfh, cgit-beta
    • add quarterly branch name
    • note that re-adding and copying a port are being investigated
  • Problem Reports (lightly touched)

Diff Detail

Repository
R9 FreeBSD doc repository
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

rene requested review of this revision.Mar 27 2021, 9:12 PM
rene created this revision.

Overall looks good

documentation/content/en/articles/committers-guide/_index.adoc
472–473

IMO we should avoid unqualified "before" -- before what? Maybe "named the same as they were in svn, branches/yyyyQn"?

4237

we might want to give suggestions about how/what to verify?

4242

typo, recorded

but maybe "of the main branch is included in the new commit message on the quarterly branch."

documentation/content/en/articles/problem-reports/_index.adoc
99 ↗(On Diff #86404)

IMO let's commit this non-ports change independently first

documentation/content/en/books/porters-handbook/order/chapter.adoc
34 ↗(On Diff #86404)

Do we generally do this today (as the first line after the $FreeBSD$)?

documentation/content/en/books/porters-handbook/special/chapter.adoc
3877 ↗(On Diff #86404)

Another change we ought to commit independently first.

documentation/content/en/books/porters-handbook/testing/chapter.adoc
237 ↗(On Diff #86404)

Another one we should update independently.

documentation/content/en/books/porters-handbook/uses/chapter.adoc
632 ↗(On Diff #86404)

another early commit

I think the workflow when committing an update needs to be rewritten completely.

documentation/content/en/articles/committers-guide/_index.adoc
472–473
2152

When you change an anchor name, you do have to check that anything referencing it in the whole documentation also gets updated. I have no idea if it is the case for this one, just saying.

2159–2160

As the release packages are built from the current quarterly branch, it should probably say that this was only used a few times and before quarterly existed.

4140–4143

There is only one way, it involves creating a branch just before the port was removed, and merging it back to main, but I don't think anyone wants to do that because "history looks horrible" using the current git tools.

I'd say this paragraph should probably not be added.

4145–4149

There is no way for this to exist, unless git starts tracking moves and copies. The paragraph should probably not be added in the first place.

4237

"build test" would be enough.

documentation/content/en/books/handbook/mirrors/_index.adoc
709 ↗(On Diff #86404)

Maybe change to this, for historic reasons ?

781 ↗(On Diff #86404)

I think this change is either wrong or incomplete.

documentation/content/en/books/handbook/ports/_index.adoc
628–632 ↗(On Diff #86404)

This should probably be put before the whole "build your own" bit, so that people know they can install a binary package first.

documentation/content/en/books/porters-handbook/order/chapter.adoc
34 ↗(On Diff #86404)

No, we don't, I think we should remove this, and finally be done with having a comment at the start of the Makefile documented as a thing.

documentation/content/en/books/porters-handbook/quick-porting/chapter.adoc
237–239 ↗(On Diff #86404)

git does not care about the current directory, the diff always has a full path name, also, -C changes the directory, so cd ../.. and -C foo/bar is a no-op.

The only change is the location of the oneko.diff file, but poeple will figure out it is in the current directory anyway.

documentation/content/en/books/porters-handbook/testing/chapter.adoc
234 ↗(On Diff #86404)

I think -v head is wrong here, the branch is named main, but maybe poudriere does something under the hood.

documentation/content/en/books/porters-handbook/upgrading/chapter.adoc
111–130 ↗(On Diff #86404)

All this is no longer valid, when you git pull, it will fetch the new changes, and then it will either do nothing with an error if you have uncommitted changes, or try to merge the changes, which can fail with merge conflicts, but in any way, merging is not a good idea. One should run git pull --rebase to make sure no merge commits are introduced.

136 ↗(On Diff #86404)

git diff will always diff the whole repository, not the current directory.

rene marked 10 inline comments as done.
  • Address updates to the committers guide
rene marked an inline comment as done and an inline comment as not done.Mar 29 2021, 8:47 PM
rene added inline comments.
documentation/content/en/articles/committers-guide/_index.adoc
472–473

Even better :)

2159–2160

Or perhaps just drop that line (branches/RELENG_n_n_n) ?

4140–4143

Fair enough. We can always add something later on.

documentation/content/en/articles/problem-reports/_index.adoc
99 ↗(On Diff #86404)

Will do.

documentation/content/en/books/porters-handbook/special/chapter.adoc
3877 ↗(On Diff #86404)

Yes.

rene marked 12 inline comments as done.
  • Address rest of feedback.
documentation/content/en/books/handbook/mirrors/_index.adoc
781 ↗(On Diff #86404)

Hm, I'll just remove that line for line now.

documentation/content/en/books/porters-handbook/order/chapter.adoc
34 ↗(On Diff #86404)

Ah, you're right, the "Created by:" line is legacy.

documentation/content/en/articles/committers-guide/_index.adoc
472–473

Ok, the quarterly branch will hopefully loose the branches/ prefix, so it should be removed here too.

documentation/content/en/books/handbook/mirrors/_index.adoc
711 ↗(On Diff #86573)
documentation/content/en/books/handbook/mirrors/_index.adoc
711 ↗(On Diff #86573)

Typo here Tfor his

Rebase for split books.

  • Address updates to the committers guide
  • Address rest of feedback.
  • Fix typo
rene marked 2 inline comments as done.Apr 3 2021, 10:58 AM
documentation/content/en/articles/committers-guide/_index.adoc
2159–2160

/branches/yyyyQn -> yyyyQn ?

documentation/content/en/articles/committers-guide/_index.adoc
2159–2160

what we have is release/x.y.z

2160–2162

what we currently have is n-eol without prefix

documentation/content/en/articles/committers-guide/_index.adoc
2159–2160

we don't have RELENG_n_n_n branches, they are tags (in below)

documentation/content/en/articles/committers-guide/_index.adoc
2159–2160

And the description sounds weird to me. Do we have literally a yyyyQn branch (and points to the latest quarterly branch)?

I think just mentioning ... which represent the quarterly branches, (e.g. 2021Q2) should be fine.

(While that's a good idea to have a quarterly branch points to the latest one.)

Comments inline.

documentation/content/en/articles/committers-guide/_index.adoc
63–64

Git repository

4140–4143

Git appears actually to DTRT with readded ports- the old history is tacked on just fine. I think that part of addport can just go, as I suggested in the original discussion.

Unfortunately copies it doesn't do well, but that's not in scope here.

This section can just go.

rene marked 8 inline comments as done.Apr 5 2021, 8:53 PM
rene added inline comments.
documentation/content/en/articles/committers-guide/_index.adoc
2159–2160

I rephrased it a bit, hopefully more clear now.

4140–4143

Also slightly rewritten the next section (moving a port) to not have dangling textual references to the now removed sections.

rene marked 2 inline comments as done.
  • Address updates to the committers guide
  • Address rest of feedback.
  • Fix typo
  • Process comments from lwhsu and crees, rewrite the move-port procedure a bit.
documentation/content/en/articles/committers-guide/_index.adoc
468–469

Legacy GitHub mirror is at https://github.com/freebsd/freebsd-ports-legacy.git , which I don't think we need to mention. We just need link to https://docs.freebsd.org/en/books/handbook/mirrors/#_external_mirrors (and add ports) there.

469–470

cgit is not mirror, it's web interface to git repository. so maybe:
The cgit repository web browser is at https://cgit.freebsd.org/ports.git

471–472

maybe we can remove mentioning to master now?

2160

what we have is release/x.y.z, e.g. release/13.0.0, note it is . not _.

imp added a subscriber: imp.

I love this. From what I've been able to spot check, this is gold. and what I've read tracks my expectations.

documentation/content/en/articles/committers-guide/_index.adoc
2308

I'd planned on deorbiting the entire svn section soon. Maybe drop this from your change to avoid conflicts?

This revision is now accepted and ready to land.Apr 6 2021, 4:47 PM
rene marked 4 inline comments as done.Apr 6 2021, 6:43 PM
rene added inline comments.
documentation/content/en/articles/committers-guide/_index.adoc
2308

The psvn script has already been removed from the ports repository, and it should be an easy conflict?

lwhsu requested changes to this revision.Tue, Apr 6, 6:52 PM
lwhsu added inline comments.
documentation/content/en/articles/committers-guide/_index.adoc
468–469

https://github.com/freebsd/freebsd-ports.git is NOT legacy GitHub mirror. It's the official mirror.

I suggest just remove this and link to https://docs.freebsd.org/en/books/handbook/mirrors/#_external_mirrors

This revision now requires changes to proceed.Tue, Apr 6, 6:52 PM
documentation/content/en/articles/committers-guide/_index.adoc
469

freebsd -> FreeBSD

469–470

This has been marked done but not changed?

2155

freebsd -> FreeBSD

2160

This has been marked done but not changed?

release/x_y_z -> release/x.y.z

4233

I suggest adding:

While note that the "merge" concept in git is different than svn. What we actually do is using cherry-pick to apply patch from the specified commit in `main` to the target branch.