Request for documentation improvement: transactions

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

Request for documentation improvement: transactions

Simon Slavin-3
<https://www.sqlite.org/lang_transaction.html>

concerns me.  I suspect it started out small and grew, without ever being rewritten.

(1) It explains four complicated issues and has no sections.  I see two possibilities: either improve that page, or split it into (A) a short page which discusses SQL syntax and API calls and (B) a separate long page which discusses how SQLite handles transactions.

(2) Minor improvement: "Any command that changes the database [...] will automatically start a transaction if one is not already in effect.".  Doesn't mention ending the transaction.  Either that could be added, or perhaps the phrase that this list evolved "wraps the command in a transaction" might be used.

(3) There's a single 12-sentence-long paragraph which describes the effects of using EXCLUSIVE and IMMEDIATE.  It comes after mentioning the more obscure SAVEPOINT mechanism, and I suspect I understand it only because I already understood the subject from reading this list.

Could there be two section headings in this document: one for the varieties of BEGIN, and the other for how SAVEPOINT and RELEASE fit into things ?

The BEGIN section can say whether IMMEDIATE implies EXCLUSIVE, or vice versa, or neither.

The SAVEPOINT section can explain expected orders for using BEGIN COMMIT ROLLBACK SAVEPOINT RELEASE, whether savepoints are nested or sequential, and such things.  And also, whether unexpectedly closing a database does COMMIT RELEASE ROLLBACK if possible.

Simon.
_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Reply | Threaded
Open this post in threaded view
|

Re: Request for documentation improvement: transactions

Richard Hipp-3
On 1/19/19, Simon Slavin <[hidden email]> wrote:
> I suspect it [the docs] started out small and grew, without ever being
> rewritten.

That is a reasonable conjecture.

I agree that the documentation could use some work.  I will eventually
get around to doing this, but I feel like making enhancements and
fixing issues in the code should have priority.

Here's the deal:  I'm very fussy about who can contribute *code* to
SQLite, in order to protect the public-domain status of the SQLite
source code and due to the intense nature of testing required to land
a change.  However, there is more flexibility for volunteers who would
like to help change the world by improving the SQLite documentation.
If you want to help, please let me know.  There is a public-domain
dedication form that you will need to fill out.  You will also need to
reside in a country that recognizes the right of authors to dedicate
their work to the public domain (basically anyplace that derives their
legal traditions from British common law).  And with that, I will give
you check-in privilege on the SQLite documentation repository
(https://sqlite.org/docsrc) and as much guidance as you need to get
starting making improvements.

--
D. Richard Hipp
[hidden email]
_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Reply | Threaded
Open this post in threaded view
|

Re: Request for documentation improvement: transactions

Andrew.Goth
In reply to this post by Simon Slavin-3
Richard Hipp wrote:
> Here's the deal:  I'm very fussy about who can contribute *code* to
> SQLite, in order to protect the public-domain status of the SQLite
> source code and due to the intense nature of testing required to land a
> change.

Sensible.  I was wondering about your policy here, since I noticed that virtually all check-ins since 2011 are made by three people.  In 2012 there were five OS X check-ins by adam, and pdr/peter.d.reid made one typo correction check-in in 2016 and another in 2014.

> However, there is more flexibility for volunteers who would like to help
> change the world by improving the SQLite documentation.
>
> If you want to help, please let me know.  There is a public-domain
> dedication form that you will need to fill out.

I was actually thinking about this earlier today, how I'd signed the contributor agreement for SQLite at the same time as I did for Fossil, yet only ever asked for commit access for Fossil.  Would you consider letting me help with SQLite documentation?  I sent you a couple documentation updates in the past, which you helped incorporate for me.  (Though I admit the biggest update I can think of was actually for Lemon whose documentation is hosted in the main SQLite repository.)

If you want to discuss, please contact me via my personal email address rather than my work email address.
------------------------------------------- CONFIDENTIALITY NOTICE: This email and any attachments are for the sole use of the intended recipient and may contain material that is proprietary, confidential, privileged or otherwise legally protected or restricted under applicable government laws. Any review, disclosure, distributing or other use without expressed permission of the sender is strictly prohibited. If you are not the intended recipient, please contact the sender and delete all copies without reading, printing, or saving..
_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Reply | Threaded
Open this post in threaded view
|

Re: Request for documentation improvement: transactions

Richard Hipp-3
On 1/19/19, [hidden email] <[hidden email]> wrote:
>
> I was actually thinking about this earlier today, how I'd signed the
> contributor agreement for SQLite at the same time as I did for Fossil, yet
> only ever asked for commit access for Fossil.  Would you consider letting me
> help with SQLite documentation?

I checked the fire-safe and found your SQLite Contributors Agreement
dated 2011-10-27.  At least, I assume it is yours.  It is signed just
"Andy Goth" and it has no address or other contact information.

Just so that no questions arise later, please fill out the form
(https://www.sqlite.org/copyright-release.pdf) again with your
complete contact information and send me just an email scan this time,
via private email. I will reply with your login credentials for
https://sqlite.org/docsrc/

--
D. Richard Hipp
[hidden email]
_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users
Reply | Threaded
Open this post in threaded view
|

Re: Request for documentation improvement: transactions

Andrew.Goth
Richard Hipp wrote:
> On 1/19/19, [hidden email] wrote:
> > I was actually thinking about this earlier today, how I'd signed the
> > contributor agreement for SQLite at the same time as I did for Fossil,
> > yet only ever asked for commit access for Fossil.  Would you consider
> > letting me help with SQLite documentation?
>
> I checked the fire-safe and found your SQLite Contributors Agreement
> dated 2011-10-27.  At least, I assume it is yours.  It is signed just
> "Andy Goth" and it has no address or other contact information.

Yeah, I signed the forms in your hotel room immediately following the AlcoBOF at the Tcl/Tk Conference, so it is indeed possible we skipped a few steps.

> Just so that no questions arise later, please fill out the form
> (https://www.sqlite.org/copyright-release.pdf) again with your complete
> contact information and send me just an email scan this time, via
> private email. I will reply with your login credentials for
> https://sqlite.org/docsrc/

I'll get that taken care of Monday when I have access to a good scanner.
------------------------------------------- CONFIDENTIALITY NOTICE: This email and any attachments are for the sole use of the intended recipient and may contain material that is proprietary, confidential, privileged or otherwise legally protected or restricted under applicable government laws. Any review, disclosure, distributing or other use without expressed permission of the sender is strictly prohibited. If you are not the intended recipient, please contact the sender and delete all copies without reading, printing, or saving..
_______________________________________________
sqlite-users mailing list
[hidden email]
http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/sqlite-users