Convert most documentation about ports to git.

[rene]

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)

[emaste]

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"?

4238

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

4243

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

[mat]

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.

4141–4144

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.

4146–4150

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.

4238

"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]

• Address updates to the committers guide

[rene]

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) ?

4141–4144

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]

• 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.

[mat]

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)

[emaste]

documentation/content/en/books/handbook/mirrors/_index.adoc

711 ↗

(On Diff #86573)

Typo here Tfor his

[rene]

• Fix typo

[rene]

Rebase for split books.

• Address updates to the committers guide
• Address rest of feedback.
• Fix typo

[lwhsu]

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

2159–2160

/branches/yyyyQn -> yyyyQn ?

[lwhsu]

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

[lwhsu]

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

2159–2160

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

[lwhsu]

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.)

[crees]

Comments inline.

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

63–64

Git repository

4141–4144

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]

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

2159–2160

I rephrased it a bit, hopefully more clear now.

4141–4144

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

[rene]

• 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.

[lwhsu]

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?

2161

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

[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?

[rene]

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]

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

[lwhsu]

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

469–470

This has been marked done but not changed?

470

freebsd -> FreeBSD

2155

freebsd -> FreeBSD

2161

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.