1Notes on upgrading awk from upstream
2
3FreeBSD imports awk from the one true awk github project. This is the blessed
4successor to Brian Kernighan's efforts to maintain awk after he left Lucent.
5
6git@github.com:onetrueawk/awk.git
7
8We also track the bsd-features branch. This is a branch that takes the
9traditional one true awk and adds features that the BSD projects have added over
10the years that are useful, but not too over the top (like bit functions).
11
12The typical update cycle goes something like:
13
14(1) Create a work tree for the vendor/one-true-awk branch
15	% cd freebsd-main
16	% git worktree create ../ota vendor/one-true-awk
17(2) Update the onetrueawk github
18	% cd ../awk
19	% git pull --rebase
20	% git branch --show-current
21	bsd-features
22	% git show-ref HEAD
23	f9affa922c5e074990a999d486d4bc823590fd93 refs/remotes/origin/HEAD
24(3) Copy that to the vendor branch and push upstream
25	% rm -rf ../ota/*	# trailing /* is important
26	% cp -a * ../ota
27	% cd ../ota
28	% git add *
29	% git commit -m"Import awk YYYYMMDD hash f9affa922c5e" # 12 places
30	% git commit --amend
31	<insert the relevant bits from the FIXES file>
32	% diff -ur ../awk .
33	# Sanity check to make sure it looks good. The vendor branch should
34	# contain the unaltered sources from upstream since it's active
35	# again (for a while we were importing submitted patches to the
36	# vendor branch given the long lag with the old upstream, but no more)
37	% git tag -a -s vendor/one-true-awk/f9affa92		# 8 places
38	<enter gpg password>
39	% git push --follow-tags freebsd vendor/one-true-awk
40(4) Merge this into main
41	% git subtree merge -P contrib/one-true-awk vendor/one-true-awk
42	# resolve any conflicts and commit
43	# Be sure to use the same or similar commit message as you did for
44	# the import. If you import multiple versions before merging to head
45	# you may need to combine the messages. Also, if there's more than
46	# a screen of changes, you may want to abstract them down into an
47	# easy to digest summary.
48	% cd usr.bin/awk
49	% sudo make check
50	# make sure all the tests pass
51	% cd ../..
52	# awk is a build tool, so test the builds
53	% make buildworld / buildkernel for amd64, armv7, i386 and aarch64 (or
54	  make universe/tinderbox if there's a lot of changes).
55	% git push freebsd
56(5) Oops, lost the race to push while testing, the following will rebase things
57	% git fetch freebsd
58	% git rebase --rebase-merges -i freebsd/main
59