Rewrite CONTRIBUTING.md

groue · groue · commit 042e220f498a · 2021-12-18T14:31:02.000+01:00
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,328 +1,93 @@
-Contributing to GRDB
-====================
+How you can Contribute
+======================
 
-**Thank you for coming!**
+- [Contribute to the GRDB codebase]
+- [Answer issues and contribute to discussions]
+- [Financial support and sponsoring]
 
-This guide is a set of tips and guidelines for contributing to the GitHub repository [groue/GRDB.swift](https://github.com/groue/GRDB.swift).
+## Contribute to the GRDB codebase
 
-- [Report Bugs]
-- [Ask Questions]
-- [Suggest an Enhancement]
-- [Submit a Pull Request]
-- [Sponsoring and Professional Support]
-- [Suggested Contributions]
-- [Non-Goals]
+1. **Install** the following tools:
 
+    - For running tests:
+        - Ruby
+        - [CocoaPods](https://cocoapods.org) (gem)
+        - [xcpretty](https://github.com/xcpretty/xcpretty) (gem)
+    - For contributing code:
+        - [Swiftlint](https://github.com/realm/SwiftLint) (present in the `$PATH` or in `/opt/homebrew/bin/`)
+    - For generating documentation:
+        - [Jazzy](https://github.com/realm/jazzy) (gem)
 
-### Report Bugs
+2. **Clone the `development` branch on your machine.**
 
-Please make sure the bug is not already reported by searching existing [issues](https://github.com/groue/GRDB.swift/issues).
+3. **Run `make SQLiteCustom` in the terminal**, at the root of the repository.
+    
+    This step is not strictly necessary if you do not plan to work on custom SQLite builds. But it will avoid a lot of warnings in Xcode.
 
-If you're unable to find an existing issue addressing the problem, [open a new one](https://github.com/groue/GRDB.swift/issues/new). Be sure to include a title and clear description, as much relevant information as possible, and a code sample or an executable test case demonstrating the expected behavior that is not occurring.
+4. **Open `GRDB.xcworkspace`.** This workspace contains six projects:
+    
+    - `GRDB.xcodeproj`: the project which contains the GRDB framework and test targets. The sources are organized in two groups:
+        - `GRDB`: GRDB sources
+        - `Tests`: GRDB tests
+    - `GRDBCustom.xcodeproj`: the project which builds GRDB with a custom SQLite build.
+    - `GRDBProfiling.xcodeproj`: a project which helps profiling GRDB with Instruments. No code here is really precious.
+    - `GRDBDemoiOS.xcodeproj`, `GRDBCombineDemo.xcodeproj`, `GRDBAsyncDemo.xcodeproj`: the demo apps.
+    
+    To work with `GRDBCustom.xcodeproj`:
+    
+    - Make sure Xcode is installed in `/Applications`.
+    - Run `make SQLiteCustom` in the terminal so that SQLite sources are present.
 
+5. **Run tests**
+    
+    You can run tests from `GRDB.xcworkspace`, after selecting your target (GRDBOSX, GRDBiOS, GRDBtvOS, from `GRDB.xcodeproj` or `GRDBCustom.xcodeproj`).
+    
+    Other tests are available in the terminal:
+    
+    ```sh
+    # Run the full test suite with the current Xcode version (this takes time).
+    make test
+    
+    # Run only a few tests (this takes less time).
+    make smokeTest
+    ```
 
-### Ask Questions
+6. **Please respect the existing coding style**
+    
+    - Get familiar with the [Swift API Design Guidelines](https://www.swift.org/documentation/api-design-guidelines/).
+    - Spaces, not tabs.
+    - Whitespace-only lines are not trimmed.
+    - Documentation comments are hard-wrapped at column 80 (Xcode > Preferences > Text Editing > Display > [X] Page guide at column: 80).
+    - No Swiftlint warning after a build.
 
-The information you are looking for is maybe already available. Check out:
 
-- the [FAQ](README.md#faq)
-- the [general documentation](README.md#documentation)
-- the [answered questions](https://github.com/groue/GRDB.swift/issues?utf8=✓&q=label%3Aquestion+)
+7. **Please provide documentation for your changes**
 
-If not, your questions are welcome in the [GRDB forums](https://forums.swift.org/c/related-projects/grdb), or in a new [GitHub issue](https://github.com/groue/GRDB.swift/issues/new). 
+    GRDB documentation is provided as reference (inline doc comments starting with `///`, see [Documentation Comment Syntax](https://github.com/apple/swift/blob/main/docs/DocumentationComments.md)), and guides ([README.md](README.md) and the [Documentation](Documentation) folder).
+    
+    GRDB is "documentation-driven", which means that nothing ships until it is supported by documentation that makes sense. Documentation makes sense when someone who is not you is able to figure out what is the purpose of your contribution, how to use it, and what are its eventual caveats and corner cases. When the documentation is hard to write, or reveals too many caveats, it is the sign that the api needs to be fixed.
+    
+8. **Open a pull request with your changes!**
 
+9. **If you are granted a push access to the repository**, check [ReleaseProcess.md](Documentation/ReleaseProcess.md) in order to publish a new GRDB version.
 
-### Suggest an Enhancement
 
-Your idea may already be listed in [Suggested Contributions], waiting for someone to pick it up.
+## Answer issues and contribute to discussions
 
-If not, contact [@groue](http://twitter.com/groue) on Twitter, or [open a new issue](https://github.com/groue/GRDB.swift/issues/new).
+Answering [issues](https://github.com/groue/GRDB.swift/issues), participating in [discussions](https://github.com/groue/GRDB.swift/discussions) and in the [forum](https://forums.swift.org/c/related-projects/grdb/36) is a great way to help, get familiar with the library, and shape its direction.
 
 
-### Submit a Pull Request
+## Financial support and sponsoring
 
-Discuss your idea first, so that your changes have a good chance of being merged in.
+GRDB is free, and openly developed by its contributors, on their free time, according to their will, needs, and availability. It is not controlled by any company.
 
-Submit your pull request against the `development` branch.
+Support is free as well, as long as it happens publicly, and is available to everyone as well as internet search engines. This excludes the private channels of social networks, closed environments such as Slack, etc.
 
-Pull requests that include tests for modified and new functionalities, inline documentation, and relevant updates to the main README.md are merged faster, because you won't have to wait for somebody else to complete your contribution.
+When you have specific development or support needs, please send an email to [Gwendal Roué](mailto:gr@pierlis.com) so that we can enter a regular business relationship through the [Pierlis](http://pierlis.com/) company, based in Paris, France.
 
+You can also [sponsor @groue via GitHub](https://github.com/sponsors/groue).
 
-### Sponsoring and Professional Support
 
-GRDB is free. It is openly developed by its contributors, on their free time, according to their will, needs, and availability. It is not controlled by any company.
-
-When you have specific development or support needs, and are willing to financially contribute to GRDB, please send an email to [Gwendal Roué](mailto:gr@pierlis.com) so that we can enter a regular business relationship through the [Pierlis](http://pierlis.com/) company, based in Paris, France.
-
-
-## Suggested Contributions
-
-You'll find below various ideas for enhancing and extending GRDB, in various areas. Your ideas can be added to this list: [Suggest an Enhancement].
-
-Legend:
-
-- :baby: **Starter Task**: get familiar with GRDB internals
-- :muscle: **Hard**: there are implementation challenges
-- :pencil: **Documentation**
-- :fire: **Experimental**: let's invent the future!
-- :bowtie: **Public API Challenge**: we'll need a very good public API
-- :hammer: **Tooling**: GRDB and its environment
-- :question: **Unknown Difficulty**
-
-The ideas, in alphabetical order:
-
-- [Associations]
-- [CloudKit]
-- [Concurrency]
-- [Custom FTS5 Auxiliary Functions]
-- [Date and Time Functions]
-- [Decode NSDecimalNumber from Text Columns]
-- [Documentation]
-- [Full Text Search Demo Application]
-- [JSON]
-- [Linux]
-- [More SQL Generation]
-- [SQL Console in the Debugger]
-- [SQLCipher in a Shared App Container]
-- [Typed Expressions]
-
-
-### Associations
-
-:bowtie: Public API Challenge :muscle: Hard :fire: Experimental
-
-Associations can be enhanced in several ways. See the "Known Issues" chapter of the [Associations Guide](Documentation/AssociationsBasics.md)
-
-
-### CloudKit
-
-:bowtie: Public API Challenge :question: Unknown Difficulty :fire: Experimental
-
-Integration with [CloudKit](https://developer.apple.com/icloud/cloudkit/) is a rich, interesting, and useful topic.
-
-It is likely that CloudKit support would exist in a separate companion library.
-
-Starting points:
-
-- [caiyue1993/IceCream](https://github.com/caiyue1993/IceCream)
-- [mentrena/SyncKit](https://github.com/mentrena/SyncKit)
-- [nofelmahmood/Seam](https://github.com/nofelmahmood/Seam)
-- [Sorix/CloudCore](https://github.com/Sorix/CloudCore)
-- [Synchronizing data with CloudKit](https://medium.com/@guilhermerambo/synchronizing-data-with-cloudkit-94c6246a3fda)
-- WWDC CloudKit sessions, including [CloudKit Best Practices](https://developer.apple.com/videos/play/wwdc2016/231/)
-
-
-### Concurrency
-
-:bowtie: Public API Challenge :muscle: Hard :pencil: Documentation
-
-GRDB has a strong focus on safe concurrency. Not only safe as "does not crash", but safe as "actively protects your application data". The topic is discussed in (too) many places:
-
-- [Concurrency Guide](Documentation/Concurrency.md)
-- [Why Adopt GRDB?](https://github.com/groue/GRDB.swift/blob/master/Documentation/WhyAdoptGRDB.md#strong-and-clear-multi-threading-guarantees)
-- [Four different ways to handle SQLite concurrency](https://medium.com/@gwendal.roue/four-different-ways-to-handle-sqlite-concurrency-db3bcc74d00e)
-- [Good Practices for Designing Record Types](https://github.com/groue/GRDB.swift/blob/master/Documentation/GoodPracticesForDesigningRecordTypes.md#fetch-in-time)
-- [Comparison between GRDB and Core Data concurrency](https://github.com/groue/GRDB.swift/issues/405)
-
-Despite this abundant documention, I regularly meet developers who don't think about eventual multi-threading gotchas, and don't design their application against them.
-
-This can be explained:
-
-- Some developers disregard potential multi-threading bugs such as data races, even if the fix is "easy". Such bugs may never happen during the development of an application. They may only impact a few users in production. It is always easier not to think about them.
-
-- Databases are often seen as plain CRUD tools, and some developers are not familiar with topics like isolation or transactions. This is especially true for developers who have experience in a managed ORM such as Core Data or Realm, or web frameworks like Rails or Django: switching to an unmanaged relational database is not an easy task.
-
-- Not all applications need to be multi-threaded.
-
-And this creates improvement opportunities:
-
-- Better documentation of GRDB concurrency
-
-- The introduction of an "ultra-safe" concurrency mode. Maybe something that restricts all database accesses to the main thread, like [FCModel](https://github.com/marcoarment/FCModel). Maybe in a separate companion library.
-
-
-### Custom FTS5 Auxiliary Functions
-
-:question: Unknown Difficulty
-
-The SQLite documentation provides [this description](https://www.sqlite.org/fts5.html) of FTS5 auxiliary functions:
-
-> An application may use FTS5 auxiliary functions to retrieve extra information regarding the matched row. For example, an auxiliary function may be used to retrieve a copy of a column value for a matched row with all instances of the matched term surrounded by html <b></b> tags.
-
-Applications can define their own [custom FTS5 auxiliary functions](https://www.sqlite.org/fts5.html#custom_auxiliary_functions) with SQLite, but GRDB does not yet provide any Swift API for that.
-
-See issue [#421](https://github.com/groue/GRDB.swift/issues/421) for more information.
-
-
-### Date and Time Functions
-
-:baby: Starter Task
-
-Believe it or not, no one has ever asked support for SQLite [Date And Time Functions](https://www.sqlite.org/lang_datefunc.html). There is surely room for a nice Swift API that makes them available.
-
-For more ideas, see:
-
-- [SQLite Core Functions](https://www.sqlite.org/lang_corefunc.html)
-- [SQLite Aggregate Functions](https://www.sqlite.org/lang_aggfunc.html)
-- [SQLite JSON functions](https://www.sqlite.org/json1.html) and [JSON], below.
-
-Functions are defined in [GRDB/QueryInterface/Support/SQLFunctions.swift](https://github.com/groue/GRDB.swift/blob/master/GRDB/QueryInterface/Support/SQLFunctions.swift).
-
-
-### Decode NSDecimalNumber from Text Columns
-
-:baby: Starter Task
-
-NSDecimalNumber currently only decodes integer and float decimal values. It would be nice if NSDecimalNumber would decode text values as well:
-
-```swift
-let number = try NSDecimalNumber.fetchOne(db, "SELECT '12.3'")!
-print(number) // prints 12.3
-```
-
-NSNumber and NSDecimalNumber support is found in [GRDB/Core/Support/Foundation/NSNumber.swift](https://github.com/groue/GRDB.swift/blob/master/GRDB/Core/Support/Foundation/NSNumber.swift)
-
-
-### Documentation
-
-:baby: Starter Task :pencil: Documentation
-
-General documentation can always be improved so that it reaches its goal: helping developers building applications.
-
-- English: the documentation has mostly been written by [@groue](http://github.com/groue) who is not a native English speaker.
-- Clarity: any chapter that is not crystal clear should be enhanced.
-- Audience: documentation should talk to several populations of developers, from beginners who need positive guidance, to SQLite experts who need to build trust.
-- Typos
-- Inaccuracies
-- etc.
-
-Inline documentation, the one which is embedded right into the source code and is displayed by Xcode when one alt-clicks an identifier, deserves the same care.
-
-If you are a good writer, your help will be very warmly welcomed.
-
-
-### Full Text Search Demo Application
-
-:baby: Starter Task :pencil: Documentation
-
-There exists a GRDB demo app for the FTS5 full-text engine: [WWDCCompanion](https://github.com/groue/WWDCCompanion).
-
-This application downloads the transcripts of WWDC sessions, and lets its user type keywords and find matching sessions, sorted by relevance.
-
-The problem is that this demo app breaks every year :sweat_smile:
-
-We'd need instead to index a stable corpus, in order to ease the maintenance of this demo app.
-
-
-### JSON
-
-:bowtie: Public API Challenge :baby: Starter Task
-
-[Codable Records] are granted with automatic JSON encoding and decoding of their complex properties. But there is still room for improvements. For example, could we put the [SQLite JSON1 extension](https://www.sqlite.org/json1.html) to some good use?
-
-
-### Linux
-
-:muscle: Hard :hammer: Tooling
-
-Swift on Linux is currently focused on the server (Vapor, Perfect, Kitura). While general server support is a [non-goal](#non-goals) of GRDB, there exists read-only servers, and Linux GUI applications, too. Linux is thus a desired platform.
-
-
-### More SQL Generation
-
-:bowtie: Public API Challenge :question: Unknown Difficulty
-
-There are several SQLite features that GRDB could natively support:
-
-- [ALTER TABLE ... RENAME COLUMN ... TO ...](https://www.sqlite.org/lang_altertable.html)
-- [ATTACH DATABASE](https://www.sqlite.org/lang_attach.html)
-- [UPSERT](https://www.sqlite.org/lang_UPSERT.html)
-- [INSERT INTO ... SELECT ...](https://www.sqlite.org/lang_insert.html)
-- [WITH RECURSIVE ...](https://www.sqlite.org/lang_with.html)
-- [RTree](https://sqlite.org/rtree.html)
-- [Windows Functions](https://www.sqlite.org/windowfunctions.html)
-- [More ideas](https://www.sqlite.org/lang.html)
-
-See [issue #575](https://github.com/groue/GRDB.swift/issues/575) for more information and guidance about the implementation of extra table alterations.
-
-
-### SQL Console in the Debugger
-
-:question: Unknown Difficulty :hammer: Tooling
-
-Sometimes one needs, in lldb, a console similar to the [Command Line Shell For SQLite](https://www.sqlite.org/cli.html).
-
-
-### SQLCipher in a Shared App Container
-
-:question: Unknown Difficulty
-
-See issue [#302](https://github.com/groue/GRDB.swift/issues/302).
-
-
-### Typed Expressions
-
-:bowtie: Public API Challenge :muscle: Hard :fire: Experimental
-
-The compiler currently does not spot type mistakes in query interface requests:
-
-```swift
-Player.filter(Column("name") == "Arthur") // OK
-Player.filter(Column("name") == 1)        // Sure
-Player.filter(Column("name") == Date())   // Legit
-```
-
-This weak typing also prevents natural-looking Swift code from producing the expected results:
-
-```swift
-// Performs arithmetic additions instead of string concatenation
-Player.select(Column("firstName") + " " + Column("lastName"))
-```
-
-It would be interesting to see what typed expressions could bring to GRDB.
-
-
-## Non-Goals
-
-GRDB is a "toolkit for SQLite databases, with a focus on application development".
-
-This definition is the reason why GRDB can provide key features such as sharp multi-threading, database observation, and first-class support for raw SQL.
-
-Features that blur this focus are non-goals:
-
-- Support for MySQL, PostgreSQL, or other database engines
-- Support for Servers
-
-
-[Ask Questions]: #ask-questions
-[Associations]: #associations
-[CloudKit]: #cloudkit
-[Codable Records]: README.md#codable-records
-[Custom FTS5 Auxiliary Functions]: #custom-fts5-auxiliary-functions
-[Database Observation]: #database-observation
-[Date and Time Functions]: #date-and-time-functions
-[Decode NSDecimalNumber from Text Columns]: #decode-nsdecimalnumber-from-text-columns
-[Documentation]: #documentation
-[Full Text Search Demo Application]: #full-text-search-demo-application
-[How is the Library Organized?]: Documentation/LibraryOrganization.md
-[How is the Repository Organized?]: Documentation/RepositoryOrganization.md
-[JSON]: #json
-[Linux]: #linux
-[More SQL Generation]: #more-sql-generation
-[Records: Splitting Database Encoding from Ability to Write in the Database]: #records-splitting-database-encoding-from-ability-to-write-in-the-database
-[Non-Goals]: #non-goals
-[Report Bugs]: #report-bugs
-[RxGRDB]: http://github.com/RxSwiftCommunity/RxGRDB
-[Concurrency]: Documentation/Concurrency.md
-[Sponsoring and Professional Support]: #sponsoring-and-professional-support
-[SQL Console in the Debugger]: #sql-console-in-the-debugger
-[SQLCipher in a Shared App Container]: #sqlcipher-in-a-shared-app-container
-[Submit a Pull Request]: #submit-a-pull-request
-[Suggest an Enhancement]: #suggest-an-enhancement
-[Suggested Contributions]: #suggested-contributions
-[Typed Expressions]: #typed-expressions
-[persistence methods]: README.md#persistence-methods
-[PersistableRecord]: README.md#persistablerecord-protocol
-[Record Comparison]: README.md#record-comparison
-[Requesting Associated Records]: Documentation/AssociationsBasics.md#requesting-associated-records
-[ValueObservation]: README.md#valueobservation
+[Contribute to the GRDB codebase]: #contribute-to-the-grdb-codebase
+[Answer issues and contribute to discussions]: #answer-issues-and-contribute-to-discussions
+[Financial support and sponsoring]: #financial-support-and-sponsoring
