MySQL++

Check-in [3aef3560ea]
Login

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

Overview
Comment:Assorted improvements to the HACKERS.md file
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 3aef3560ea82607c5c2493c026cb722470416eda49b15eb32b7cf101e519258f
User & Date: tangent 2019-04-22 18:44:25
Context
2019-04-22
18:50
Added info on the GitHub mirror to HACKERS.md. check-in: 8b0728e18d user: tangent tags: trunk
18:44
Assorted improvements to the HACKERS.md file check-in: 3aef3560ea user: tangent tags: trunk
2019-02-15
23:53
Fixed a circular make dependency in way the libssqls2parse target was defined. GNU make 3.81 was griping about it. check-in: 296f546849 user: tangent tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to HACKERS.md.

5
6
7
8
9
10
11






12
13
14
15
16
17
18
..
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
..
79
80
81
82
83
84
85

86
87
88
89
90

91
92
93
94
95
96
97
...
314
315
316
317
318
319
320

321
322
323


324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
...
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
...
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
...
515
516
517
518
519
520
521

522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
...
555
556
557
558
559
560
561
562




## Code Repository Access

MySQL++ uses the [Fossil][fsl] [distributed version control
system][dvcs]. See its [quick start guide][fslq] if you are unfamilar
with Fossil.







You must be running Fossil version 2.1 or higher to access the MySQL++
repository. If your operating system includes an older Fossil package,
you will either have to install [an official binary][fslb] or [build
it from source][fsls].

To clone the MySQL++ repository anonymously, say:
................................................................................

We created a new subdirectory because the `open` command checks out the
tip of the repository's trunk into the current directory by default.

As with `mysqlpp.fossil`, you can call the working directory anything
you like. I actually prefer a working tree that looks like this:

    ~/museum/                  # Where fossils are kept
        mysqlpp.fossil
    ~/src/                     # Working tree for software projects
        mysqlpp/
            skull/             # Fossil head, get it?   I crack me up.
            trunk -> skull/    # Alias to match Fossil branch naming
            some-branch/       # Separately-opened working branch
            3.2.3/             # Tagged release checkout

Fossil will let you make any modifications you like to your local
repository copy. For those with privileges on the upstream copy,
checkins get automatically synced with it by default. (If you prefer
Git or Mercurial style two-phase commits, you can say `fossil settings
autosync off`.) If you don't have such permissions, you just modify
your local copy, then have to merge in upstream changes when updating
your local clone.

Developers are expected to make all changes that affect the libary's
API, ABI, or behavior on a branch, rather than check such changes
directly into the trunk. Once we have discussed the change on the
[mailing list][ml] and resolved any isssues with the experimental
branch, it will be merged into the trunk.

Creating a branch in Fossil is scary-simple, to the point that those
coming from other version control systems may ask, "Is that really all
there is to it?" Yes, really, this is it:

    $ fossil checkin --branch new-branch-name

................................................................................
At some point, the trunk version becomes the next major version. Stable
versions become either tags or branches. (The only difference between
tags and branches in Fossil is that branches may have subsequent changes
made to them.)

[avh]:  https://tangentsoft.com/mysqlpp/wiki?name=Abridged+Version+History
[dvcs]: http://en.wikipedia.org/wiki/Distributed_revision_control

[fsl]:  http://fossil-scm.org/
[fslb]: http://fossil-scm.org/index.html/uv/download.html
[fslq]: http://fossil-scm.org/index.html/doc/trunk/www/quickstart.wiki
[fsls]: http://fossil-scm.org/index.html/doc/trunk/www/build.wiki
[ml]:   https://lists.mysql.com/plusplus/



## Bootstrapping the Library

When you check out MySQL++ from Fossil, there are a lot of things
"missing" as compared to a distributed tarball, because the Fossil
repository contains only source files, no generated files.  The
................................................................................
do something, it's likely it just can't do it. Bakefile is a
high-level abstraction of build systems in general, so it'll never
support all the particulars of every odd build system out there.

[bkl]: https://tangentsoft.com/mysqlpp/file/mysql%2B%2B.bkl



## Submitting Patches

If you wish to submit a patch to the library, please send it to the


[MySQL++ mailing list][ml].  We want patches in unified diff format.

We will also accept trivial patches not needing discussion as text
in a Fossil ticket.

The easiest way to get a unified diff is to check out a copy of the
current MySQL++ tree as described above. Then make your change, `cd`
to the MySQL++ root directory, and ask Fossil to generate the patch
for you:

    $ fossil diff > mychange.patch

If your patch adds new files, moves files, or needs to be understood in
terms of multiple checkins, it's best to do that work on a [private
local branch][pbr], then send a [bundle][fb] instead of a patch.

If you've sent patches to MySQL++ before and don't have a Fossil
developer login, another alternative is to ask for a login before you
begin work so that your changes are automatically sync'd to the main
Fossil repository as you work, so you don't have to send bundles or
patch files. We generally don't refuse such requests if you've already
proven your ability to work well with the MySQL++ project.
................................................................................

The `diff` command is part of every Unix and Linux system, and should be
installed by default. If you're on a Windows machine, GNU diff is part
of [Cygwin](http://cygwin.com/). Fossil is also available for all of
these systems. There are no excuses for not being able to make unified
diffs. :)

[fb]:  http://fossil-scm.org/index.html/help?cmd=bundle
[pbr]: https://tangentsoft.com/mysqlpp/file/HACKERS.md#private


## The MySQL++ Code Style

Every code base should have a common code style. Love it or
hate it, here are MySQL++'s current code style rules:

................................................................................

-   DOS line endings, again for the Notepad reason. And on modern Unixy
    platforms, the tools cope with DOS line endings reasonably well.
    Better than the converse, anyway.


When in doubt, mimic what you see in the current code. When still in
doubt, ask on the [mailing list][ml].


## Testing Your Proposed Change

MySQL++ includes a self-test mechanism called `dtest`. It's a Bourne
shell script, run much like `exrun`:

................................................................................
patches. In the past, we've had broken ports that were missing important
library features, or that crashed when built in certain ways. Few people
will knowingly use a crippled version of MySQL++, since there are
usually acceptable alternatives.  Therefore, such ports become
maintenance baggage with little compensating value.



## <a name="private"></a>Maintaining a Private Repository

Although Fossil syncs changes back to the `tangentsoft.com/mysqlpp`
Fossil repository by default, it is possible to maintain a private copy
that simply pulls changes in occasionally.

The first step is to turn off the auto-sync feature:

     $ fossil set autosync 0

Then, I recommend that you make any local changes on a branch:

    ...hack, hack, hack...
    $ fossil ci --branch my-local-branch

After you give the `--branch` option on a checkin, Fossil automatically
................................................................................
modify your clone, only the working checkout directory. You must then
say `fossil ci` once you're happy with the merge. Until then, all the
usual Fossil commands like `fossil diff` and `fossil status` will help
you come to that decision.

If you ever decide to contribute your private branch to the MySQL++
project, there are a couple of easy ways to achieve that. Ask about it
on the [mailing list][ml] if you find yourself in this situation.









>
>
>
>
>
>







 







|



|
|
<
|


|
|
|
|
|
|




|
|







 







>

|
|
|
<
>







 







>


|
>
>
|













|







 







|
<







 







|







 







>
|

|
|




|







 







|
>
>
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
..
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
..
84
85
86
87
88
89
90
91
92
93
94
95

96
97
98
99
100
101
102
103
...
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
...
360
361
362
363
364
365
366
367

368
369
370
371
372
373
374
...
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
...
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
...
564
565
566
567
568
569
570
571
572
573


## Code Repository Access

MySQL++ uses the [Fossil][fsl] [distributed version control
system][dvcs]. See its [quick start guide][fslq] if you are unfamilar
with Fossil.

That Fossil repository is also [mirrored to GitHub][ghm] nightly, but
this is a read-only mirror, meant for use with Git automation tooling.
For example, you could use MySQL++ as a submodule in a larger Git
project via this channel. [Changes to MySQL++](#patches) still must go
go through the Fossil repository.

You must be running Fossil version 2.1 or higher to access the MySQL++
repository. If your operating system includes an older Fossil package,
you will either have to install [an official binary][fslb] or [build
it from source][fsls].

To clone the MySQL++ repository anonymously, say:
................................................................................

We created a new subdirectory because the `open` command checks out the
tip of the repository's trunk into the current directory by default.

As with `mysqlpp.fossil`, you can call the working directory anything
you like. I actually prefer a working tree that looks like this:

    ~/museum/                  # Where one keeps fossils, right?
        mysqlpp.fossil
    ~/src/                     # Working tree for software projects
        mysqlpp/
            trunk/             # Primary working branch for MySQL++
            other-branch/      # Separate working branch checkout

            3.2.3/             # Older tagged stable release checkout

Fossil will let you make any modifications you like to your local
repository copy. For those with check-in privileges on the upstream
copy, changes get automatically synced with it by default. (If you
prefer Git or Mercurial style two-phase commits, you can say `fossil set
autosync off`.) If you don't have such permissions, check-ins just
modify your local repository clone, then have to merge in upstream
changes when updating your local clone.

Developers are expected to make all changes that affect the libary's
API, ABI, or behavior on a branch, rather than check such changes
directly into the trunk. Once we have discussed the change on the
[forum][for] and resolved any isssues with the experimental branch, it
will be merged into the trunk.

Creating a branch in Fossil is scary-simple, to the point that those
coming from other version control systems may ask, "Is that really all
there is to it?" Yes, really, this is it:

    $ fossil checkin --branch new-branch-name

................................................................................
At some point, the trunk version becomes the next major version. Stable
versions become either tags or branches. (The only difference between
tags and branches in Fossil is that branches may have subsequent changes
made to them.)

[avh]:  https://tangentsoft.com/mysqlpp/wiki?name=Abridged+Version+History
[dvcs]: http://en.wikipedia.org/wiki/Distributed_revision_control
[for]:  https://tangentsoft.com/mysqlpp/froum/
[fsl]:  http://fossil-scm.org/
[fslb]: http://fossil-scm.org/fossil/uv/download.html
[fslq]: http://fossil-scm.org/fossil/doc/trunk/www/quickstart.wiki
[fsls]: http://fossil-scm.org/fossil/doc/trunk/www/build.wiki

[ghm]:  https://github.com/tangentsoft/mysqlpp


## Bootstrapping the Library

When you check out MySQL++ from Fossil, there are a lot of things
"missing" as compared to a distributed tarball, because the Fossil
repository contains only source files, no generated files.  The
................................................................................
do something, it's likely it just can't do it. Bakefile is a
high-level abstraction of build systems in general, so it'll never
support all the particulars of every odd build system out there.

[bkl]: https://tangentsoft.com/mysqlpp/file/mysql%2B%2B.bkl


<a id="patches"></a>
## Submitting Patches

If you wish to submit a patch to the library, it’s probably simplest to
paste it into a [forum post][for] if it’s small. If it’s large, put it
in Pastebin or similar, then link to it from a forum post.  We want
patches in unified diff format.

We will also accept trivial patches not needing discussion as text
in a Fossil ticket.

The easiest way to get a unified diff is to check out a copy of the
current MySQL++ tree as described above. Then make your change, `cd`
to the MySQL++ root directory, and ask Fossil to generate the patch
for you:

    $ fossil diff > mychange.patch

If your patch adds new files, moves files, or needs to be understood in
terms of multiple checkins, it's best to do that work on a [private
local branch](#private), then send a [bundle][fb] instead of a patch.

If you've sent patches to MySQL++ before and don't have a Fossil
developer login, another alternative is to ask for a login before you
begin work so that your changes are automatically sync'd to the main
Fossil repository as you work, so you don't have to send bundles or
patch files. We generally don't refuse such requests if you've already
proven your ability to work well with the MySQL++ project.
................................................................................

The `diff` command is part of every Unix and Linux system, and should be
installed by default. If you're on a Windows machine, GNU diff is part
of [Cygwin](http://cygwin.com/). Fossil is also available for all of
these systems. There are no excuses for not being able to make unified
diffs. :)

[fb]:  http://fossil-scm.org/fossil/help?cmd=bundle



## The MySQL++ Code Style

Every code base should have a common code style. Love it or
hate it, here are MySQL++'s current code style rules:

................................................................................

-   DOS line endings, again for the Notepad reason. And on modern Unixy
    platforms, the tools cope with DOS line endings reasonably well.
    Better than the converse, anyway.


When in doubt, mimic what you see in the current code. When still in
doubt, ask on [the forum][for].


## Testing Your Proposed Change

MySQL++ includes a self-test mechanism called `dtest`. It's a Bourne
shell script, run much like `exrun`:

................................................................................
patches. In the past, we've had broken ports that were missing important
library features, or that crashed when built in certain ways. Few people
will knowingly use a crippled version of MySQL++, since there are
usually acceptable alternatives.  Therefore, such ports become
maintenance baggage with little compensating value.


<a name="private"></a>
## Maintaining a Private Repository

Although Fossil syncs changes back to the [MySQL++ Fossil
repository][home] by default, it is possible to maintain a private copy
that simply pulls changes in occasionally.

The first step is to turn off the auto-sync feature:

     $ fossil set autosync off

Then, I recommend that you make any local changes on a branch:

    ...hack, hack, hack...
    $ fossil ci --branch my-local-branch

After you give the `--branch` option on a checkin, Fossil automatically
................................................................................
modify your clone, only the working checkout directory. You must then
say `fossil ci` once you're happy with the merge. Until then, all the
usual Fossil commands like `fossil diff` and `fossil status` will help
you come to that decision.

If you ever decide to contribute your private branch to the MySQL++
project, there are a couple of easy ways to achieve that. Ask about it
on [the forum][for] if you find yourself in this situation.

[home]: https://tangentsoft.com/mysqlpp/