JSOC/CM/release.howto

Art's suggested release recipe:

1. Notify users (jsoc_dev@sun.stanford.edu) that a new release will be
built.  Allow users time to submit changes they want in the new
release.  This includes changes made by the CM that have not been
committed.  

2. Update $JSOCROOT/base/jsoc_version.h to the latest release version
and build again (make clean, make universe).  The version macros
should be of the form:

#define jsoc_version "V3R5"
#define jsoc_vers_num (305)

cvs commit $JSOCROOT/base/jsoc_version.h.

3. Add a new file, JSOC/CM/V<MAJ>.<MIN>/release.notes. This has the
release notes (see below).  Commit.

4. Create a tag for the new release.
  a. Create the full-JSOC-release tags
       i. /home/jsoc/dlsource.pl -o tag -f sdp -t Ver_<MAJ>-<MIN>
      ii. /home/jsoc/dlsource.pl -o untag -f sdp -t Ver_LATEST
     iii. /home/jsoc/dlsource.pl -o tag -f sdp -t Ver_LATEST
  b. Create the NetDRMS-release tags
       i. /home/jsoc/dlsource.pl -o tag -f net -t NetDRMS_Ver_<MAJ>-<MIN>
      ii. /home/jsoc/dlsource.pl -o untag -f net -t Ver_DRMSLATEST
     iii. /home/jsoc/dlsource.pl -o tag -f net -t Ver_DRMSLATEST

5. Now you must build all production release executables with the release jsoc
version numbers in place ("V3R5" and "305" in this example). Ensure
that the tag was successfully created and create actual release
binaries (not just the binaries in your sandbox).  Login as the 'jsoc'
user, cd to /home/jsoc/cvs, and run "/home/jsoc/dlsource.pl -o checkout 
-f sdp -r Ver_<MAJ>-<MIN>" and build on all machines supported. Do the same in 
/home/jsoc/cvs/Development/. 

6. Edit $JSOCROOT/base/jsoc_version.h, but not the version of this file
in a production directory.The version macros should be of the form:

#define jsoc_version "V3R5X"
#define jsoc_vers_num (-305)

The "X" and "-" denote that binaries were created from non-release code.

commit $JSOCROOT/base/jsoc_version.h.

7. Send instructions for using the new release to users.

================================================================================
Example New Release Instructions


                       Release Notes JSOC V3.8         12Sep2007
                       -----------------------         ---------

A release is a set of files, each having a specific version.  And a release typcially
has a version number because over time you have newer and newer releases of the 
same product.  For example, a hypothetical 1.3 release may contain fileA#1.8, 
fileB#1.2, fileC#2.2 and a 1.4 release may contain fileA#2.5, fileB#2.1, fileC#2.9. 
JSOC releases are similarly versioned and contain a set of such files.  JSOC release
code is guaranteed to compile on cluster nodes (eg., n00, n02).  The resulting binaries
have been minimally tested.  At the time of the creation of the release, the
release versions of each file will be the most recent.  But as time passes, newer versions 
of some files will be made, and there is no guarantee that these changes will
not destabilize JSOC (ie., they may cause JSOC to no longer compile or execute
properly).  

There are several ways to use this release.  If you wish to simply use pre-built
binaries, you can simply use the production binaries, which are located at 
/home/production/cvs/JSOC.  Every time a release is created, the binaries in
this location get updated.  Only the production user can update these binaries.
So, you could run /home/production/cvs/JSOC/bin/linux_x86_64/show_keys, for example.
If instead you want to work with stable source files, then you must have a sandbox,
which is a local copy (in your home directory) of the files in the cvs depot.  
You would probably want to work with a sandbox if you plan on making eventual 
changes to the depot files.  Changes you make to your sandbox files are not visible 
to other users until you "commit" those changes back to the cvs depot.  Please see
"If You Don't Have a Sandbox" below for more information on how to create a sandbox.  
There is also a "working" release which resides in in /home/jsoc/cvs/JSOC.  New 
files may be placed here and existing files may be edited for common use before the 
next official release.  Each time a release gets created, the source and binaries of 
the working release get updated.  WARNING: the files you see here may not be stable 
since by the time you see them, another user may have edited them. Only the production 
release is guaranteed to be stable and unchanged between releases.

Obtaining the Release
---------------------
To update your working directory to this release, or to check-out this release anew, 
please visit http://jsoc.stanford.edu/jsocwiki/CvsInit. Please keep in mind that
users may have modified files since the release was created, so use of the 
scripts documented in the web page may result in a working directory whose
content is not identical to the release.  If updating, you can supply 
the flag "-R" to the jsoc_update.csh and jsoc_sync.csh scripts to download the
latest release.  This will ensure that your working directory has the exact, latest
release versions of the files (eg., jsoc_sync.csh -R). If checking-out, 
you can supply the argument "-r Ver_LATEST" to the "cvs checkout" command
to achieve the analogous result, but for a fresh checkout.  WARNING: if you use 
the "-R" or "-r" flags, please use only jsoc_update.csh or jsoc_sync.csh to update 
your sources thereafter.  Use of "-R" or "-r Ver_LATEST" will result in a cvs
"sticky flag" being set.  jsoc_update.csh and jsoc_sync.csh clear this sticky flag.

Additional Info
---------------
If you are unfamiliar with the use of cvs see the file:
JSOC/CM/working_with_sandbox.txt.

There's a linux4 cvs gui at xim:/usr/bin/lincvs
Also on our jsoc web page:

http://jsoc.stanford.edu/cvs/JSOC/

Use the Apache cvs gui to see the diffs. For example, go to
http://jsoc.stanford.edu/cvs/JSOC/base/drms/
and click on the name in the File column and then click on
"diffs to previous #" to see the diffs.

End Example New Release Instructions
================================================================================

--Art Amezcua 9/12/2007


                                        /home/jim/cvs/JSOC/CM/release.howto

Make sure the cvs/JSOC/base/jsoc_version.h is updated.

A release is done from a sandbox. Get the production user sandbox to work:

> cd /home/production/cvs/JSOC

d00:/home/production/cvs/JSOC>  $JSOCROOT/jsoc_update.csh

Do a sanity check on the make log files:
$JSOCROOT/make_jsoc_linux_X86_64.log
#$JSOCROOT/make_jsoc_linux_ia64.log
$JSOCROOT/make_jsoc_linux_ia32.log


-----------------------------------------------------------------------------
When all the makes are ok, tag all the most recent revisions in the repository:

> cvs -d /home/cvsuser/cvsroot rtag -r HEAD Ver_1-0 JSOC

To remove this tag do:

> cvs -d /home/cvsuser/cvsroot rtag -d Ver_1-0 JSOC

NOTE: Tell users about Phil's script cvs/JSOC/jsoc_update.csh  to do
their release update.


***************OLD STUFF BELOW******************************************
-----------------------------------------------------------------------------

Resync with the repository:

> cvs update -APd >& cvsupdate.log

Inspect cvsupdate.log for any "C " status.

       C file
         A  conflict  was detected while trying to merge your changes to file
         with changes from the source repository.  file  (the  copy  in  your
         working  directory) is now the result of attempting to merge the two
         revisions; an unmodified copy of your file is also in  your  working
         directory, with the name .#file.revision where revision is the revi-
         sion that your modified file started from.  Resolve the conflict 

-----------------------------------------------------------------------------
Check for any files that have not been commited (not Status: Up-to-date):

> cvsstatus     (NOTE: s/b an alias for $JSOCROOT/scripts/cvsstatus.pl)

Determine if any modified files need to be committed or replaced with the
repository version before proceeding.

-----------------------------------------------------------------------------
Get the all the makes to work:
> ssh production@lws               (and then again for d00 and n00(32bit))
> cd /home/production/cvs/JSOC
####(OLD) > setenv ORACLE_HOME /u01/app/oracle/product/10.1.0/db_1
> ./configure -force  (for n00: ./configure -force -client)
(may have to do a make cleandep; make depend)
(ignore modification time in future msgs)

> make clean
> make -j 4 >& make.log.lws        (run 4 jobs in parallel for speed)

############## ONLY HAD TO DO THIS THE FIRST TIME ############################
!!!!!!!!!!!!!!!!!Check that libsum, sumsapi, and sum dirs use gcc !!!!!!!!!!!
!!!!!!!!!!! Don't have to do this if gcc is already in the Makefile !!!!!!!!!
Now go to the dirs that need to have the gcc compile and edit Makefile:
cd /home2/production/cvs/JSOC/base/
cd sums/libs/pg
vi Makefile
***ADD after the line:
include ../../make.mk

###Mod by JA after configure is run#########################
CC = gcc
CFLAGS = -std=gnu99 -g -Wall -O0 -Wno-comment -Wno-parentheses

And then do
>make clean
>make
And do the same for cd ../sumsapi/ and cd ../sum/
############## ONLY HAD TO DO THIS THE FIRST TIME ############################


Revision:	1.13
Committed:	Thu Jun 2 23:30:38 2011 UTC (12 years, 3 months ago) by arta
Branch:	MAIN
CVS Tags:	Ver_6-0, Ver_6-1, Ver_6-2, Ver_6-3, Ver_6-4, NetDRMS_Ver_8-8, Ver_8-5, Ver_5-14, Ver_5-13, Ver_LATEST, NetDRMS_Ver_LATEST, NetDRMS_Ver_8-12, NetDRMS_Ver_8-10, NetDRMS_Ver_8-11, NetDRMS_Ver_9-1, NetDRMS_Ver_9-0, NetDRMS_Ver_9-3, NetDRMS_Ver_9-2, NetDRMS_Ver_9-5, NetDRMS_Ver_9-4, Ver_7-0, NetDRMS_Ver_9-41, Ver_9-41, NetDRMS_Ver_8-4, NetDRMS_Ver_8-5, NetDRMS_Ver_8-6, Ver_8-8, NetDRMS_Ver_8-7, Ver_8-2, Ver_9-3, Ver_8-0, Ver_8-1, Ver_8-6, Ver_8-7, Ver_8-4, Ver_8-11, Ver_7-1, Ver_9-1, Ver_8-3, Ver_9-5, Ver_9-4, Ver_8-10, Ver_9-2, Ver_8-12, Ver_9-0, HEAD
Changes since 1.12:	+20 -40 lines
Log Message:	Update the release howto to use dlsource.pl, which makes it easy to update CVS tags and do checkouts.
#	User	Rev	Content
1	arta	1.1	Art's suggested release recipe:
2
3	arta	1.8	1. Notify users (jsoc_dev@sun.stanford.edu) that a new release will be
4			built. Allow users time to submit changes they want in the new
5			release. This includes changes made by the CM that have not been
6			committed.
7
8	arta	1.13	2. Update $JSOCROOT/base/jsoc_version.h to the latest release version
9	arta	1.8	and build again (make clean, make universe). The version macros
10			should be of the form:
11	arta	1.1
12			#define jsoc_version "V3R5"
13			#define jsoc_vers_num (305)
14
15	arta	1.13	cvs commit $JSOCROOT/base/jsoc_version.h.
16	arta	1.8
17	arta	1.13	3. Add a new file, JSOC/CM/V<MAJ>.<MIN>/release.notes. This has the
18	arta	1.8	release notes (see below). Commit.
19
20	arta	1.13	4. Create a tag for the new release.
21			a. Create the full-JSOC-release tags
22			i. /home/jsoc/dlsource.pl -o tag -f sdp -t Ver_<MAJ>-<MIN>
23			ii. /home/jsoc/dlsource.pl -o untag -f sdp -t Ver_LATEST
24			iii. /home/jsoc/dlsource.pl -o tag -f sdp -t Ver_LATEST
25			b. Create the NetDRMS-release tags
26			i. /home/jsoc/dlsource.pl -o tag -f net -t NetDRMS_Ver_<MAJ>-<MIN>
27			ii. /home/jsoc/dlsource.pl -o untag -f net -t Ver_DRMSLATEST
28			iii. /home/jsoc/dlsource.pl -o tag -f net -t Ver_DRMSLATEST
29	arta	1.12
30	arta	1.13	5. Now you must build all production release executables with the release jsoc
31	arta	1.8	version numbers in place ("V3R5" and "305" in this example). Ensure
32			that the tag was successfully created and create actual release
33			binaries (not just the binaries in your sandbox). Login as the 'jsoc'
34	arta	1.13	user, cd to /home/jsoc/cvs, and run "/home/jsoc/dlsource.pl -o checkout
35			-f sdp -r Ver_<MAJ>-<MIN>" and build on all machines supported. Do the same in
36			/home/jsoc/cvs/Development/.
37	arta	1.8
38	arta	1.13	6. Edit $JSOCROOT/base/jsoc_version.h, but not the version of this file
39			in a production directory.The version macros should be of the form:
40	arta	1.1
41			#define jsoc_version "V3R5X"
42			#define jsoc_vers_num (-305)
43
44			The "X" and "-" denote that binaries were created from non-release code.
45	arta	1.7
46	arta	1.13	commit $JSOCROOT/base/jsoc_version.h.
47	arta	1.8
48	arta	1.13	7. Send instructions for using the new release to users.
49	arta	1.1
50			================================================================================
51			Example New Release Instructions
52
53
54			Release Notes JSOC V3.8 12Sep2007
55			----------------------- ---------
56
57			A release is a set of files, each having a specific version. And a release typcially
58			has a version number because over time you have newer and newer releases of the
59			same product. For example, a hypothetical 1.3 release may contain fileA#1.8,
60			fileB#1.2, fileC#2.2 and a 1.4 release may contain fileA#2.5, fileB#2.1, fileC#2.9.
61			JSOC releases are similarly versioned and contain a set of such files. JSOC release
62			code is guaranteed to compile on cluster nodes (eg., n00, n02). The resulting binaries
63			have been minimally tested. At the time of the creation of the release, the
64			release versions of each file will be the most recent. But as time passes, newer versions
65			of some files will be made, and there is no guarantee that these changes will
66			not destabilize JSOC (ie., they may cause JSOC to no longer compile or execute
67			properly).
68
69			There are several ways to use this release. If you wish to simply use pre-built
70			binaries, you can simply use the production binaries, which are located at
71	arta	1.3	/home/production/cvs/JSOC. Every time a release is created, the binaries in
72	arta	1.1	this location get updated. Only the production user can update these binaries.
73	arta	1.3	So, you could run /home/production/cvs/JSOC/bin/linux_x86_64/show_keys, for example.
74	arta	1.1	If instead you want to work with stable source files, then you must have a sandbox,
75			which is a local copy (in your home directory) of the files in the cvs depot.
76			You would probably want to work with a sandbox if you plan on making eventual
77			changes to the depot files. Changes you make to your sandbox files are not visible
78			to other users until you "commit" those changes back to the cvs depot. Please see
79			"If You Don't Have a Sandbox" below for more information on how to create a sandbox.
80	arta	1.3	There is also a "working" release which resides in in /home/jsoc/cvs/JSOC. New
81	arta	1.1	files may be placed here and existing files may be edited for common use before the
82			next official release. Each time a release gets created, the source and binaries of
83			the working release get updated. WARNING: the files you see here may not be stable
84			since by the time you see them, another user may have edited them. Only the production
85			release is guaranteed to be stable and unchanged between releases.
86
87	arta	1.4	Obtaining the Release
88			---------------------
89			To update your working directory to this release, or to check-out this release anew,
90			please visit http://jsoc.stanford.edu/jsocwiki/CvsInit. Please keep in mind that
91			users may have modified files since the release was created, so use of the
92			scripts documented in the web page may result in a working directory whose
93			content is not identical to the release. If updating, you can supply
94			the flag "-R" to the jsoc_update.csh and jsoc_sync.csh scripts to download the
95			latest release. This will ensure that your working directory has the exact, latest
96			release versions of the files (eg., jsoc_sync.csh -R). If checking-out,
97			you can supply the argument "-r Ver_LATEST" to the "cvs checkout" command
98			to achieve the analogous result, but for a fresh checkout. WARNING: if you use
99			the "-R" or "-r" flags, please use only jsoc_update.csh or jsoc_sync.csh to update
100			your sources thereafter. Use of "-R" or "-r Ver_LATEST" will result in a cvs
101			"sticky flag" being set. jsoc_update.csh and jsoc_sync.csh clear this sticky flag.
102	arta	1.1
103			Additional Info
104			---------------
105			If you are unfamiliar with the use of cvs see the file:
106	arta	1.3	JSOC/CM/working_with_sandbox.txt.
107	arta	1.1
108			There's a linux4 cvs gui at xim:/usr/bin/lincvs
109			Also on our jsoc web page:
110
111	arta	1.3	http://jsoc.stanford.edu/cvs/JSOC/
112	arta	1.1
113			Use the Apache cvs gui to see the diffs. For example, go to
114	arta	1.2	http://jsoc.stanford.edu/cvs/JSOC/base/drms/
115	arta	1.1	and click on the name in the File column and then click on
116			"diffs to previous #" to see the diffs.
117
118			End Example New Release Instructions
119			================================================================================
120
121			--Art Amezcua 9/12/2007
122
123
124
125
126	arta	1.3	/home/jim/cvs/JSOC/CM/release.howto
127	arta	1.1
128	arta	1.2	Make sure the cvs/JSOC/base/jsoc_version.h is updated.
129	arta	1.1
130			A release is done from a sandbox. Get the production user sandbox to work:
131
132	arta	1.3	> cd /home/production/cvs/JSOC
133	arta	1.1
134	arta	1.3	d00:/home/production/cvs/JSOC> $JSOCROOT/jsoc_update.csh
135	arta	1.1
136			Do a sanity check on the make log files:
137			$JSOCROOT/make_jsoc_linux_X86_64.log
138			#$JSOCROOT/make_jsoc_linux_ia64.log
139			$JSOCROOT/make_jsoc_linux_ia32.log
140
141
142			-----------------------------------------------------------------------------
143			When all the makes are ok, tag all the most recent revisions in the repository:
144
145	arta	1.3	> cvs -d /home/cvsuser/cvsroot rtag -r HEAD Ver_1-0 JSOC
146	arta	1.1
147			To remove this tag do:
148
149	arta	1.3	> cvs -d /home/cvsuser/cvsroot rtag -d Ver_1-0 JSOC
150	arta	1.1
151	arta	1.3	NOTE: Tell users about Phil's script cvs/JSOC/jsoc_update.csh to do
152	arta	1.1	their release update.
153
154
155
156			*************OLD STUFF BELOW****************************************
157			-----------------------------------------------------------------------------
158
159			Resync with the repository:
160
161			> cvs update -APd >& cvsupdate.log
162
163			Inspect cvsupdate.log for any "C " status.
164
165			C file
166			A conflict was detected while trying to merge your changes to file
167			with changes from the source repository. file (the copy in your
168			working directory) is now the result of attempting to merge the two
169			revisions; an unmodified copy of your file is also in your working
170			directory, with the name .#file.revision where revision is the revi-
171			sion that your modified file started from. Resolve the conflict
172
173			-----------------------------------------------------------------------------
174			Check for any files that have not been commited (not Status: Up-to-date):
175
176			> cvsstatus (NOTE: s/b an alias for $JSOCROOT/scripts/cvsstatus.pl)
177
178			Determine if any modified files need to be committed or replaced with the
179			repository version before proceeding.
180
181			-----------------------------------------------------------------------------
182			Get the all the makes to work:
183			> ssh production@lws (and then again for d00 and n00(32bit))
184	arta	1.3	> cd /home/production/cvs/JSOC
185	arta	1.1	####(OLD) > setenv ORACLE_HOME /u01/app/oracle/product/10.1.0/db_1
186			> ./configure -force (for n00: ./configure -force -client)
187			(may have to do a make cleandep; make depend)
188			(ignore modification time in future msgs)
189
190			> make clean
191			> make -j 4 >& make.log.lws (run 4 jobs in parallel for speed)
192
193			############## ONLY HAD TO DO THIS THE FIRST TIME ############################
194			!!!!!!!!!!!!!!!!!Check that libsum, sumsapi, and sum dirs use gcc !!!!!!!!!!!
195			!!!!!!!!!!! Don't have to do this if gcc is already in the Makefile !!!!!!!!!
196			Now go to the dirs that need to have the gcc compile and edit Makefile:
197	arta	1.2	cd /home2/production/cvs/JSOC/base/
198			cd sums/libs/pg
199	arta	1.1	vi Makefile
200			***ADD after the line:
201			include ../../make.mk
202
203			###Mod by JA after configure is run#########################
204			CC = gcc
205			CFLAGS = -std=gnu99 -g -Wall -O0 -Wno-comment -Wno-parentheses
206
207			And then do
208			>make clean
209			>make
210			And do the same for cd ../sumsapi/ and cd ../sum/
211			############## ONLY HAD TO DO THIS THE FIRST TIME ############################
212
213
214