1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
|
#+TITLE: How to release AUCTeX
#+AUTHOR: Mosè Giordano
#+DATE: [2019-10-31 Thu]
This document descriptes the steps for AUCTeX maintainer to do a new release of
the package.
You will need to upload files to GNU FTP servers. In order to do so, we use an
automated system. Before starting, [[https://www.gnu.org/prep/maintain/html_node/Automated-FTP-Uploads.html#Automated-FTP-Uploads][register for automated uploading]] if you did
not already.
** AUCTeX package [0/3]
Note: I recommend iterating a few times the following steps in a test repository
(of course excluding uploading of the package to the FTP server) to check that
everything goes well, before actually doing the release.
- [ ] Synchronise with the [[https://savannah.gnu.org/git/?group=auctex][remote repository on Savannah]]: =git pull=
- [ ] Prepare for new release [0/3]
- [ ] Update AUCTeX version and copyright year in =configure.ac=,
=doc/tex-ref.tex=, and =latex/preview.dtx=
- [ ] Make sure that all relevant changes are mentioned in =doc/changes.texi=
- [ ] Update =RELEASE= [0/3]
- [ ] Update release version
- [ ] Update list of changes: use =CHANGES= (which is generated from
=doc/changes.texi=, you may need to run =make= to update it after
changes above)
- [ ] Update any other relevant information, like the list of
contributors, or required version of GNU Emacs
- [ ] Commit all the above changes with a title like
#+BEGIN_SRC
; Prepare for new release
#+END_SRC
- [ ] Towards the end of the top-level =Makefile= there are the instructions on
how to do the release. Follow them.
- The instructions may mention how to build the XEmacs and Windows packages,
but you do not need to do that if you decided to stop providing those
packages
- Make sure that the patch for =gendocs.sh= in the =www-docs= target applies
correctly, otherwise you will need to update it. Remember to update it in
the =gendocspath= branch of the AUCTeX remote repository too.
- [[https://www.nongnu.org/texi2html/][=texi2html=]] is needed to build the online documentation. So far, version
1.8.2 has been used and tested. Version 5.0 may not be fully compatible (in
particular, I have found that
=auctex-dist/www/manual/manual/auctex/index.html= may be a broken link using
=texi2html= 5.0)
** Website [0/6]
You now have to update the information about latest AUCTeX version on the
website, and the online documentation. The website is maintained in a CVS
repository on Savannah. Read the [[https://savannah.gnu.org/cvs/?group=www][Savannah instructions about how to use CVS for
webpages]] (remember to replace =www= with =auctex= as project). The command to
checkout the repository locally should be
#+BEGIN_SRC sh
cvs -z3 -d:ext:YOUR_USER_NAME@cvs.savannah.gnu.org:/web/auctex co auctex
#+END_SRC
In order to access the [[http://web.cvs.savannah.gnu.org/viewvc/auctex/auctex/][remote CVS repository]], you also need to have the
environment variable =CVS_RSH= set to =ssh=:
#+BEGIN_SRC sh
export CVS_RSH=ssh
#+END_SRC
You can also browse the [[http://web.cvs.savannah.gnu.org/viewvc/auctex/][content of the CVS repository]].
- [ ] Remove all =manual/{auctex,preview-latex}.*= files, and replace them with
the =auctex-dist/www/manual/manual/{auctex,preview-latex}.*= files from AUCTeX
repository
- [ ] Remove all =manual/auctex/*.html= files, and replace them with the
=auctex-dist/www/manual/manual/auctex.*= files from AUCTeX repository
- [ ] Remove all =manual/preview-latex/*.html= files, and replace them with the
=auctex-dist/www/manual/manual/preview-latex.*= files from AUCTeX repository
- [ ] Update AUCTeX version and date in files in =src/= directory. When you are
done, run the script =./genpages.sh=
- [ ] Update the =ChangeLog=
- [ ] Register all changes. You can use for example =vc-mode= in Emacs: [0/2]
- [ ] Register all new files with =i=
- [ ] Select all files in the same state with =m= and do check in/out with =v=
- [ ] To delete files not needed anymore I don’t know a better way than
deleting them on disk, then manually running the command =cvs remove= in the
local repository and then in =vc-mode= select all files marked as "removed"
with =m= and make the change effective with =v=
Simple shell commands to help replacing the old files with the new ones:
#+BEGIN_SRC sh
# Set these variables
AUCTEX_DIR="...."
AUCTEX_WEBPAGES_DIR="...."
rm "${AUCTEX_WEBPAGES_DIR}"/manual/{auctex,preview-latex}.* \
"${AUCTEX_WEBPAGES_DIR}"/manual/auctex/*.html \
"${AUCTEX_WEBPAGES_DIR}"/manual/preview-latex/*.html
cp "${AUCTEX_DIR}"/auctex-dist/www/manual/manual/{auctex,preview-latex}.* "${AUCTEX_WEBPAGES_DIR}"/manual/.
cp "${AUCTEX_DIR}"/auctex-dist/www/manual/manual/auctex/* "${AUCTEX_WEBPAGES_DIR}"/manual/auctex/.
cp "${AUCTEX_DIR}"/auctex-dist/www/manual/manual/preview-latex/* "${AUCTEX_WEBPAGES_DIR}"/manual/preview-latex/.
#+END_src
** =preview= package to CTAN
Upload the =preview= tarball generated with =make preview-ball= to CTAN as a
"package update" using the [[https://ctan.org/upload][upload form]].
My understanding is that you can use your own name and email in the "Your name"
and "Your email" fields only if you are an authorised uploader of
=preview=. David and Mosè are authorised, I do not know if other people are
authorised. If in doubt, ask them.
For the other fields, re-use the details of the [[https://ctan.org/pkg/preview][=preview= page on CTAN]].
- Name of your contribution: =preview=
- Maintainer: The AUCTeX team
- Summary: Extract bits of a LaTeX source for output
- Suggested CTAN directory: =/macros/latex/contrib/preview=
- License type: GNU General Public License, version 3
- Home page: https://www.gnu.org/software/auctex/preview-latex.html
- Bug tracker: https://debbugs.gnu.org/cgi/pkgreport.cgi?package=auctex
- Support: https://lists.gnu.org/mailman/listinfo/auctex
- Announcements: https://lists.gnu.org/mailman/listinfo/info-auctex
- Repository: https://git.savannah.gnu.org/gitweb/?p=auctex.git
- Developers: https://lists.gnu.org/mailman/listinfo/auctex-devel
** Announcement email
Send the announcement email to
- info-auctex@gnu.org, auctex@gnu.org, info-gnu@gnu.org, ctan@dante.de
Include a =Mail-Followup-To= to auctex@gnu.org. So the header of the email
should be something like (adapt as necessary)
#+BEGIN_SRC message
From: YOUR NAME <YOUR_EMAIL_ADDRESS@gnu.org>
To: info-auctex@gnu.org, auctex@gnu.org, info-gnu@gnu.org, ctan@dante.de
Subject: AUCTeX X.Y released
Mail-Followup-To: auctex@gnu.org
--text follows this line--
#+END_SRC
The content of the email is simply the content of the =RELEASE= file.
** ELPA Release
*** One-time setup
GNU AUCTeX is hosted as a so-called "externals" package in the GNU ELPA Git
repository. So the first step is to add the GNU ELPA Git repository as an
additional remote to your AUCTeX Git repository. In the following example, the
remote name is "elpa".
#+BEGIN_SRC sh
git remote add elpa ssh://<user>@git.savannah.gnu.org/srv/git/emacs/elpa.git
#+END_SRC
AUCTeX is kept in the ~externals/auctex~ branch of the ELPA repository.
*** Making an ELPA release
1. Switch to the ~externals/auctex~ branch by issuing ~git checkout
externals/auctex~.
2. Ensure you are up-to-date using ~git pull~ and ~git fetch --all~.
3. Merge the commits which have taken place in the normal auctex development on
the ~master~ branch using ~git merge origin/master~.
4. In case of conflicts, edit, and commit.
5. Check that everything compiles by running ~make -f GNUMakefile~.
6. Push your changes to the elpa remote (~git push~).
Just updating the ~externals/auctex~ branch by merging in the changes from the
AUCTeX ~master~ branch won't have any effect on the version one can get in
Emacs' package manager. To do an actual release which will be published, you
have to do the following steps in addition.
7. Edit the line ~;; Version: X.Y.Z~ in the file ~auctex.el~. For ELPA
releases, Y and Y match the latest AUCTeX version and Z is incremented for
every ELPA release of that AUCTeX version. Z starts with 0, so AUCTeX
12.2.0 should be (almost) identical to the AUCTeX release 12.2.
8. Commit that change with this Git commit message (but do not push yet!). The
ChangeLog formatted line must be written in exactly this way for the next
step!
#+BEGIN_EXAMPLE
Release GNU AUCTeX X.Y.Z
* GNU AUCTeX Version X.Y.Z released.
#+END_EXAMPLE
9. Run ~make -f GNUMakefile~ again. In the output you should see that the
above version is inserted into several files, e.g., the info documentation.
The version change is gotten from the current HEAD of the branch. That's
the reason the commit message has to be in exactly this format.
10. Commit again to have the version changes captured (but don't push).
11. Now our commit from step 8 announces the release but only the commit after
that captures the version changes. Therefore, we "fixup" the commit from
step 10 into that of step 8 using ~git rebase --interactive HEAD^^~ and
changing the "pick" to "fixup" for the commit of step 10. Save and exit.
Now the commit of step 8 includes the one of step 10.
12. Now push your changes, and the new GNU AUCTeX ELPA release will hopefully
be available within a few hours.
*** Caveats
It has happened in the past that a new GNU AUCTeX ELPA release didn't really
appear although all steps in the previous section have been performed. The
reason was that there has been a new style file whose copyright header didn't
have the correct format, and ELPA's tooling is pretty strict about that.
In order to check that all copyrights are ok, clone/checkout the master branch
of the ELPA Git repository.
#+BEGIN_SRC sh
# Clone if not done before.
git clone ssh://<user>@git.savannah.gnu.org/srv/git/emacs/elpa.git
# Otherwise checkout the master brach
git checkout master
# Get the latest changes
git pull
#+END_SRC
To update the external packages (such as AUCTeX), run ~make externals~ in the
root directory of the ELPA repository. Then run ~make check_copyrights~ which
looks for all files without FSF-copyright line which are not listed in a
special copyright_exceptions file. As result, it spits out a diff between the
actual and expected copyright exceptions. If the diff is empty (or at least
doesn't mention an AUCTeX file), everything is fine.
** Bumping required Emacs version
It happens from time to time that AUCTeX requires a newer Emacs
version. For this, the following files in the main directory has to
be adjusted.
- [ ] =auctex.el.in= :: Change the ~;; Package-Requires:~ cookie in
the header.
- [ ] =configure.ac= :: Change the argument of ~EMACS_CHECK_VERSION~
- [ ] =tex-site.el.in= :: Change the number after ~emacs-major-version~
- [ ] =tex.el= :: Change the number after ~emacs-major-version~
Other files to be updated accordingly:
- [ ] =doc/changes.texi= :: Add an entry under *News* about the
required version.
- [ ] =doc/faq.texi= :: Adjust the number in this sentence:
=@AUCTeX{} was tested with @w{GNU Emacs XX.X}=.
- [ ] =doc/install.texi= :: Adjust the number in ~@node Prerequisites~:
=@item GNU Emacs XX.X or higher=.
- [ ] =doc/preview-faq.texi= :: Adjust the number in ~@section Requirements~
=@previewlatex{} nominally requires @w{GNU Emacs} with a version of
at least XX.X.=.
- [ ] =RELEASE= :: Update the version of GNU Emacs in the
"Requirements" section.
|
