Documentation Source Text

Check-in [b44ff2a454]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Clean up and extend the privatebranch.html document.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: b44ff2a454aa98500a6b1516eda2cc27ad81a6ed
User & Date: drh 2009-12-15 14:34:43
Context
2009-12-21
15:45
Add the new "private" target to the makefile - used to build the requirements matrix that includes TH3 hyperlinks. check-in: 3d7eb1e8f0 user: drh tags: trunk
2009-12-15
14:34
Clean up and extend the privatebranch.html document. check-in: b44ff2a454 user: drh tags: trunk
14:05
Fix a typo in the privatebranch.html document. check-in: 04a7a8e7dd user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/privatebranch.in.

35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
..
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
...
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
...
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
...
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
...
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
...
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
...
336
337
338
339
340
341
342
343
344
345
346
347
348





























This article is not trying to impose a particular procedure on 
maintainers of private branches.  The point of this article is to offer
an example of one process for maintaining a private branch which can
be used as a template for designing processes best suited for the
circumstances of each individual project.</p>

<img src="images/private_branch.gif" align="right">
<h1>2.0 The Basic Idea</h1>


<p>We propose to use the
[http://www.fossil-scm.org | fossil software configuration management]
system to set up two branches.  One branch (the "public branch" or "trunk")
contains the published SQLite sources and the other branch is the 
private branch which contains the code that is customized for the project.
................................................................................
<p>The cycle above can be repeated many times.  The
diagram shows a third SQLite release, 3.6.17 in
circle (6).  The private branch maintainer can do
another merge in order to incorporate the changes
moving from (4) to (6) into the private branch, resulting
in version (7).</p>

<h1>3.0 The Procedure</h1>

<p>The remainder of this document will guide the reader through
the steps needed to maintain a private branch.  The general idea
is the same as outlined above.  This section merely provides more
detail.</p>

<p>We emphasize again that these steps are not intended to be the only
acceptable method for maintaining private branch.  This approach
is one of many.  Use this document as a baseline for preparing
project-specific procedures.  Do not be afraid to experiment.</p>

<h2>3.1 Obtain The Software</h2>

<p>[http://www.fossil-scm.org/ | Fossil] is a computer program
that must be installed on your machine before you use it.
Fortunately, installing fossil is very easy.  Fossil is a single
"*.exe" file that you simply download and run.  To uninstall fossil,
simply delete the exe file.  
[http://www.fossil-scm.org/index.html/doc/tip/www/quickstart.wiki | Detailed instructions] for installing and getting started with
fossil are available on the 
[http://www.fossil-scm.org | fossil website].</p>

<h2>3.2 Create A Project Repository</h2>

<p>Create a fossil repository to host the private branch using the
following command:</p>

<blockquote><pre>
fossil new private-project.fossil
</pre></blockquote>
................................................................................
fossil open private-project.fossil
</pre></blockquote>

<p>You can have multiple checkouts of the same project if you want. 
And you can "clone" the repository to different machines so that multiple
developers can use it.  See the fossil website for further information.</p>

<h2>3.3 Installing The SQLite Baseline In Fossil</h2>

<p>The repository created in the previous step is initially empty.  The
next step is to load the baseline SQLite release - circle (1) in the diagram
above.</p>

<p>Begin by obtaining a copy of SQLite in whatever form you use it.
The public SQLite you obtain should be as close to your private edited
................................................................................

<blockquote><pre>
fossil timeline
fossil info
fossil status
</pre></blockquote>

<h2>3.4 Creating The Private Branch</h2>

<p>The previous step created circle (1) in the diagram above.
This step will create circle (2).  Run the following command:</p>

<blockquote><pre> 
fossil branch new private trunk -bgcolor "#add8e8"
</pre></blockquote>
................................................................................
fossil update trunk
</pre></blockquote>

<p>Normally, fossil will modify all the files in your checkout when switching
between the private and the public branches.  But at this point, the files
are identical in both branches so not modifications need to be made.</p>

<h2>3.5 Adding Customizations To The Code In The Private Branch</h2>

<p>Now it is time to make the private, custom modifications to SQLite
which are the whole point of this exercise.  Switch to the private branch
(if you are not already there) using the "<tt>fossil update private</tt>"
command, then bring up the source files in your text editor and make
whatever changes you want to make.  Once you have finished making
changes, commit those changes using this command:</p>
................................................................................
<p>Note that in the diagram above, we showed the private edits as a single
commit.  This was for clarity of presentation only.  There is nothing to stop
you from doing dozens or hundreds of separate tiny changes and committing
each separately.  In fact, making many small changes is the preferred way
to work.  The only reason for doing all the changes in a single commit
is that it makes the diagram easier to draw.</p>

<h2>3.6 Incorporating New Public SQLite Releases</h2>

<p>Suppose that after a while (about a month, usually) a new version of
SQLite is released: 3.6.16.  You will want to incorporate this new
public version of SQLite into your repository in the public branch (the
trunk).  To do this, first change your repository over to the trunk:</p>

<blockquote><pre>
................................................................................
<p>If you made NL to CR-NL line ending changes or space to tab
indentation changes in the original baseline, make the same changes
to the new source file.</p>

<p>Once everything is ready, run the "<tt>fossil commit</tt>" command to
check in the changes.  This creates circle (4) in the diagram above.</p>

<h2>3.7 Merging Public SQLite Updates Into The Private Branch</h2>

<p>The next step is to move the changes in the public branch over into
the private branch.  In other words, we want to create circle (5) in the
diagram above.  Begin by changing to the private branch using
"<tt>fossil update private</tt>".  Then type this command:</p>

<blockquote><pre>
................................................................................
conflicts and manually resolve the conflicts.</p>

<p>After resolving conflicts, many users like to compile and test the
new version before committing it to the repository.  Or you can commit
first and test later.  Either way, run the "<tt>fossil commit</tt>"
command to check-in the circle (5) version.

<h2>3.8 Further Updates</h2>

<p>As new versions of SQLite are released, repeat steps 3.6 and 3.7 to
add changes in the new release to the private branch.
Additional private changes can be
made on the private branch in between releases if desired.</p>




































|







 







|











|










|







 







|







 







|







 







|







 







|







 







|







 







|





>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
..
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
...
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
...
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
...
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
...
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
...
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
...
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
This article is not trying to impose a particular procedure on 
maintainers of private branches.  The point of this article is to offer
an example of one process for maintaining a private branch which can
be used as a template for designing processes best suited for the
circumstances of each individual project.</p>

<img src="images/private_branch.gif" align="right">
<h2>2.0 The Basic Idea</h2>


<p>We propose to use the
[http://www.fossil-scm.org | fossil software configuration management]
system to set up two branches.  One branch (the "public branch" or "trunk")
contains the published SQLite sources and the other branch is the 
private branch which contains the code that is customized for the project.
................................................................................
<p>The cycle above can be repeated many times.  The
diagram shows a third SQLite release, 3.6.17 in
circle (6).  The private branch maintainer can do
another merge in order to incorporate the changes
moving from (4) to (6) into the private branch, resulting
in version (7).</p>

<h2>3.0 The Procedure</h2>

<p>The remainder of this document will guide the reader through
the steps needed to maintain a private branch.  The general idea
is the same as outlined above.  This section merely provides more
detail.</p>

<p>We emphasize again that these steps are not intended to be the only
acceptable method for maintaining private branch.  This approach
is one of many.  Use this document as a baseline for preparing
project-specific procedures.  Do not be afraid to experiment.</p>

<h3>3.1 Obtain The Software</h3>

<p>[http://www.fossil-scm.org/ | Fossil] is a computer program
that must be installed on your machine before you use it.
Fortunately, installing fossil is very easy.  Fossil is a single
"*.exe" file that you simply download and run.  To uninstall fossil,
simply delete the exe file.  
[http://www.fossil-scm.org/index.html/doc/tip/www/quickstart.wiki | Detailed instructions] for installing and getting started with
fossil are available on the 
[http://www.fossil-scm.org | fossil website].</p>

<h3>3.2 Create A Project Repository</h3>

<p>Create a fossil repository to host the private branch using the
following command:</p>

<blockquote><pre>
fossil new private-project.fossil
</pre></blockquote>
................................................................................
fossil open private-project.fossil
</pre></blockquote>

<p>You can have multiple checkouts of the same project if you want. 
And you can "clone" the repository to different machines so that multiple
developers can use it.  See the fossil website for further information.</p>

<h3>3.3 Installing The SQLite Baseline In Fossil</h3>

<p>The repository created in the previous step is initially empty.  The
next step is to load the baseline SQLite release - circle (1) in the diagram
above.</p>

<p>Begin by obtaining a copy of SQLite in whatever form you use it.
The public SQLite you obtain should be as close to your private edited
................................................................................

<blockquote><pre>
fossil timeline
fossil info
fossil status
</pre></blockquote>

<h3>3.4 Creating The Private Branch</h3>

<p>The previous step created circle (1) in the diagram above.
This step will create circle (2).  Run the following command:</p>

<blockquote><pre> 
fossil branch new private trunk -bgcolor "#add8e8"
</pre></blockquote>
................................................................................
fossil update trunk
</pre></blockquote>

<p>Normally, fossil will modify all the files in your checkout when switching
between the private and the public branches.  But at this point, the files
are identical in both branches so not modifications need to be made.</p>

<h3>3.5 Adding Customizations To The Code In The Private Branch</h3>

<p>Now it is time to make the private, custom modifications to SQLite
which are the whole point of this exercise.  Switch to the private branch
(if you are not already there) using the "<tt>fossil update private</tt>"
command, then bring up the source files in your text editor and make
whatever changes you want to make.  Once you have finished making
changes, commit those changes using this command:</p>
................................................................................
<p>Note that in the diagram above, we showed the private edits as a single
commit.  This was for clarity of presentation only.  There is nothing to stop
you from doing dozens or hundreds of separate tiny changes and committing
each separately.  In fact, making many small changes is the preferred way
to work.  The only reason for doing all the changes in a single commit
is that it makes the diagram easier to draw.</p>

<h3>3.6 Incorporating New Public SQLite Releases</h3>

<p>Suppose that after a while (about a month, usually) a new version of
SQLite is released: 3.6.16.  You will want to incorporate this new
public version of SQLite into your repository in the public branch (the
trunk).  To do this, first change your repository over to the trunk:</p>

<blockquote><pre>
................................................................................
<p>If you made NL to CR-NL line ending changes or space to tab
indentation changes in the original baseline, make the same changes
to the new source file.</p>

<p>Once everything is ready, run the "<tt>fossil commit</tt>" command to
check in the changes.  This creates circle (4) in the diagram above.</p>

<h3>3.7 Merging Public SQLite Updates Into The Private Branch</h3>

<p>The next step is to move the changes in the public branch over into
the private branch.  In other words, we want to create circle (5) in the
diagram above.  Begin by changing to the private branch using
"<tt>fossil update private</tt>".  Then type this command:</p>

<blockquote><pre>
................................................................................
conflicts and manually resolve the conflicts.</p>

<p>After resolving conflicts, many users like to compile and test the
new version before committing it to the repository.  Or you can commit
first and test later.  Either way, run the "<tt>fossil commit</tt>"
command to check-in the circle (5) version.

<h3>3.8 Further Updates</h3>

<p>As new versions of SQLite are released, repeat steps 3.6 and 3.7 to
add changes in the new release to the private branch.
Additional private changes can be
made on the private branch in between releases if desired.</p>

<h2>4.0 Variations</h2>

<p>Since this document was first written, the canonical SQLite source code
has been moved from the venerable CVS system into a Fossil repository at
[http://www.sqlite.org/src].  This means that if you are working with
canonical SQLite source code (as opposed to the [amalgamation] source code
files, sqlite3.c and sqlite3.h) then you can create a private repository
simply by cloning the official repository:</p>

<blockquote><pre>
fossil clone http://www.sqlite.org/src private-project.fossil
</pre></blockquote>

<p>This command both creates the new repository and populates it with
all the latest SQLite could.  You can the create a private branch as
described in section 3.4.</p>

<p>When the private repository is created by cloning, incorporating new
public SQLite releases becomes much easier too.  To pull in all of the
latest changes from the public SQLite repository, simply move into
the open check-out and do:</p>

<blockquote><pre>
fossil update
</pre></blockquote>

<p>Then continue to merge the changes in "trunk" with your "private"
changes as described in section 3.7.</p>