Page MenuHomeFreeBSD

Convert most documentation about ports to git.
ClosedPublic

Authored by rene on Mar 27 2021, 9:12 PM.
Tags
None
Referenced Files
F80135515: D29450.id86404.diff
Thu, Mar 28, 9:50 AM
Unknown Object (File)
Jan 14 2024, 10:40 PM
Unknown Object (File)
Dec 23 2023, 3:33 AM
Unknown Object (File)
Dec 16 2023, 9:53 AM
Unknown Object (File)
Nov 11 2023, 1:07 PM
Unknown Object (File)
Nov 9 2023, 11:30 AM
Unknown Object (File)
Nov 7 2023, 8:24 PM
Unknown Object (File)
Oct 10 2023, 12:06 PM
Subscribers

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
No Lint Coverage
Unit
No Test Coverage
Build Status
Buildable 38293
Build 35182: arc lint + arc unit

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
474

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

4287

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

4292

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

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
474
2153

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.

2161–2162

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.

4151–4154

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.

4186–4190

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.

4287

"build test" would be enough.

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

Maybe change to this, for historic reasons ?

782

I think this change is either wrong or incomplete.

documentation/content/en/books/handbook/ports/_index.adoc
628–632

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
474

Even better :)

2161–2162

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

4151–4154

Fair enough. We can always add something later on.

documentation/content/en/articles/problem-reports/_index.adoc
99

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
782

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
474

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–713
documentation/content/en/books/handbook/mirrors/_index.adoc
711–713

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
2161

/branches/yyyyQn -> yyyyQn ?

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

what we have is release/x.y.z

2164

what we currently have is n-eol without prefix

documentation/content/en/articles/committers-guide/_index.adoc
2161–2162

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

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

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
64

Git repository

4151–4154

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
2161

I rephrased it a bit, hopefully more clear now.

4151–4154

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
469–470

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.

470–471

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

473–474

maybe we can remove mentioning to master now?

2165

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.Apr 6 2021, 6:52 PM
lwhsu added inline comments.
documentation/content/en/articles/committers-guide/_index.adoc
469–470

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.Apr 6 2021, 6:52 PM
documentation/content/en/articles/committers-guide/_index.adoc
470–471

This has been marked done but not changed?

471

freebsd -> FreeBSD

2156

freebsd -> FreeBSD

2165

This has been marked done but not changed?

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

4282

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.