Skip to content

Latest commit

 

History

History
339 lines (206 loc) · 14.2 KB

CONTRIBUTING.md

File metadata and controls

339 lines (206 loc) · 14.2 KB

Contributing to GRDB

Thank you for coming!

This guide is a set of tips and guidelines for contributing to the GitHub repository groue/GRDB.swift.

Report Bugs

Please make sure the bug is not already reported by searching existing issues.

If you're unable to find an existing issue addressing the problem, open a new one. 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.

Ask Questions

The information you are looking for is maybe already available. Check out:

If not, your questions are welcome in the GRDB forums, or in a new GitHub issue.

Suggest an Enhancement

Your idea may already be listed in Suggested Contributions, waiting for someone to pick it up.

If not, contact @groue on Twitter, or open a new issue.

Submit a Pull Request

Discuss your idea first, so that your changes have a good chance of being merged in.

Submit your pull request against the development branch.

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.

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é so that we can enter a regular business relationship through the Pierlis 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:

  • 👶 Starter Task: get familiar with GRDB internals
  • 💪 Hard: there are implementation challenges
  • 📝 Documentation
  • 🔥 Experimental: let's invent the future!
  • :bowtie: Public API Challenge: we'll need a very good public API
  • 🔨 Tooling: GRDB and its environment
  • ❓ Unknown Difficulty

The ideas, in alphabetical order:

Associations

:bowtie: Public API Challenge 💪 Hard 🔥 Experimental

Associations can be enhanced in several ways. See the "Known Issues" chapter of the Associations Guide

CloudKit

:bowtie: Public API Challenge ❓ Unknown Difficulty 🔥 Experimental

Integration with CloudKit is a rich, interesting, and useful topic.

It is likely that CloudKit support would exist in a separate companion library.

Starting points:

Concurrency

:bowtie: Public API Challenge 💪 Hard 📝 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:

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. Maybe in a separate companion library.

Custom FTS5 Auxiliary Functions

❓ Unknown Difficulty

The SQLite documentation provides this description 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 tags.

Applications can define their own custom FTS5 auxiliary functions with SQLite, but GRDB does not yet provide any Swift API for that.

See issue #421 for more information.

Date and Time Functions

👶 Starter Task

Believe it or not, no one has ever asked support for SQLite Date And Time Functions. There is surely room for a nice Swift API that makes them available.

For more ideas, see:

Functions are defined in GRDB/QueryInterface/Support/SQLFunctions.swift.

Decode NSDecimalNumber from Text Columns

👶 Starter Task

NSDecimalNumber currently only decodes integer and float decimal values. It would be nice if NSDecimalNumber would decode text values as well:

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

Documentation

👶 Starter Task 📝 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 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

👶 Starter Task 📝 Documentation

There exists a GRDB demo app for the FTS5 full-text engine: 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 😅

We'd need instead to index a stable corpus, in order to ease the maintenance of this demo app.

JSON

:bowtie: Public API Challenge 👶 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 to some good use?

Linux

💪 Hard 🔨 Tooling

Swift on Linux is currently focused on the server (Vapor, Perfect, Kitura). While general server support is a non-goal 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 ❓ Unknown Difficulty

There are several SQLite features that GRDB could natively support:

See issue #575 for more information and guidance about the implementation of extra table alterations.

Reactive Database Observation

👶 Starter Task

We already have the GRDBCombine and RxGRDB companion libraries.

More choices of reactive engines would help more developers enjoy GRDB.

SQL Console in the Debugger

❓ Unknown Difficulty 🔨 Tooling

Sometimes one needs, in lldb, a console similar to the Command Line Shell For SQLite.

SQLCipher in a Shared App Container

❓ Unknown Difficulty

See issue #302.

Typed Expressions

:bowtie: Public API Challenge 💪 Hard 🔥 Experimental

The compiler currently does not spot type mistakes in query interface requests:

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:

// 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