@@ -55,34 +55,81 @@ release should involve:
5555* Updating ` spec/YYYY.MM/conf.py `
5656
5757 ``` diff
58+ ...
5859 - from array_api_stubs import _draft as stubs_mod
5960 + from array_api_stubs import _YYYY_MM as stubs_mod
6061 ...
6162 - release = "DRAFT"
6263 + release = "YYYY.MM"
64+ ...
6365 ```
6466
6567* Updating ` spec/_ghpages/versions.json `
6668
6769 ``` diff
6870 {
6971 + "YYYY.MM": "YYYY.MM",
72+ ...
7073 ```
7174
7275* Updating ` Makefile `
7376
7477 ``` diff
78+ ...
7579 -sphinx-build "$(SOURCEDIR)/PREVIOUS.VER" "$(BUILDDIR)/PREVIOUS.VER" $(SPHINXOPTS)
7680 + -sphinx-build "$(SOURCEDIR)/YYYY.MM" "$(BUILDDIR)/YYYY.MM" $(SPHINXOPTS)
7781 - -cp -r "$(BUILDDIR)/PREVIOUS.VER" "$(BUILDDIR)/latest"
7882 + -cp -r "$(BUILDDIR)/YYYY.MM" "$(BUILDDIR)/latest"
83+ ...
7984 ```
8085
8186These changes should be committed and tagged. The next draft should then be
82- created. TODO: instructions. See this [ StackOverflow question] ( https://stackoverflow.com/q/74365771/5193926 )
83- for background
87+ created. To preserve git history for both the new release and the next draft:
88+
89+ 1 . Create and checkout to a new temporary branch.
90+
91+ ``` sh
92+ $ git checkout -b tmp
93+ ```
94+
95+ 2 . Make an empty commit. <sup >This is required so merging the temporary branch
96+ (4.) is not automatic.</sup >
97+
98+ ``` sh
99+ $ git commit --allow-empty -m " Empty commit for draft at YYYY.MM "
100+ ```
101+
102+ 3 . Checkout back to the branch you are making a spec release in.
103+
104+ ``` sh
105+ $ git checkout YYYY.MM-release
106+ ```
107+
108+ 4 . Merge the temporary branch, specifying no commit and no fast-forwarding.
109+
110+ ``` sh
111+ $ git merge --no-commit --no-ff tmp
112+ Automatic merge went well; stopped before committing as requested
113+ ```
114+
115+ 5 . Checkout the ` spec/draft/ ` files from the temporary branch.
116+
117+ ``` sh
118+ $ git checkout tmp -- spec/draft/
119+ ```
120+
121+ 6 . Commit your changes.
122+
123+ ``` sh
124+ $ git commit -m " Copy YYYY.MM as draft with preserved git history"
125+ ```
126+
127+ You can run ` git blame ` on both ` spec/YYYY.MM ` and ` spec/draft ` files to verify
128+ we've preserved history. See this [ StackOverflow question] ( https://stackoverflow.com/q/74365771/5193926 )
129+ for more background on the approach we use.
130+
131+ <!-- TODO: write a script to automate/standardise spec releases -->
84132
85- <!-- TODO: write a script to automate/standardise this -->
86133
87134## Contributors ✨
88135
0 commit comments