Onboarding repository stadiamaps/maplibre-swiftui-dsl-playground

[ianthetechie]

Current: https://github.com/stadiamaps/maplibre-swiftui-dsl-playground

Proposed: https://github.com/maplibre/swiftui-dsl (I think we can probably drop "playground" at this point)

Motivation

We started this project because there was no good story for integrating MapLibre into SwiftUI. It was a bit of an experiment, so we started it in our own org, but I believe that the experiment has been successful and we have seen great buy-in from the MapLibre iOS dev community already.

While the project is not a 100% feature-complete wrapper yet, it is very much usable and is progressing as "real-world" users integrate it and submit PRs for new functionality. That makes it a great time to move it under the MapLibre umbrella in my opinion :)

Acceptance

• [x] Any two board members must agree to accept a new repository. Approved by: @birkskyum, @nyurik

Licensing

• [X] The repo license is BSD-3 or MIT. Repos may allow dual-licensing under other open source licenses, e.g. MIT OR Apache.
• [x] The repo contains Copyright (c) <year> MapLibre contributors in license file(s) and in the readme.

Special files

• [x] /README.md Description, link to the main maplibre.org page, name of the OSM-US Slack channel for discussions and an invite link, etc
• [x] /LICENSE Dual-licensed repos may have additional files like LICENSE-MIT and LICENSE-APACHE
• [x] /SECURITY_POLICY.txt Add the text:

  For an up-to-date policy refer to
  https://github.com/maplibre/maplibre/blob/main/SECURITY_POLICY.txt

• [x] /CONTRIBUTING.md
• [x] The repo has Pull Request and Issue Templates in /.github dir.
• [x] The repo has /.github/FUNDING.yml file copied from maplibre-gl-js/funding
• [x] /CODE_OF_CONDUCT.md This file should only link to our primary code of conduct. Use this markup for consistency: # Contributor Covenant [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](https://github.com/maplibre/maplibre/blob/main/CODE_OF_CONDUCT.md)

Repo Settings

General page

• [x] [Features] Disable unused features like wiki.
• [x] [Features] Enable Sponsorships checkbox (see also FUNDING.yaml above).
• [x] [Features] Enable Preserve this repository.
• [x] [Pull Requests] Community is encouraged to use squash merge. Disable other merge types if possible.
• [x] [Pull Requests] Enable Automatically delete head branches.

Access

• [x] The repo has at least one admin who is ideally not part of the Governing Board: <@ianthetechie>

Branches

• [X] The primary branch is named main.
• [x] Set up branch rules to require CI pass and an approval before merge. For smaller projects it might be OK to ignore this rule.

Miscelaneous

• [x] The repo must not have any personal branches. All work should be done on forks and submitted via PRs, including by the admins.
• [x] Repo has a proper GitHub description and an optional web site Use the gear icon in the upper right corner of the repo page.
• [X] CI automatically runs on all pull requests before merging using GitHub actions
• [ ] Grant admin rights to the board members and automation accounts for packages
  • npmjs.com: package settings / invite: maplibreorg nyurik klokan lseelenbinder wipfli
  • crates.io: package settings / add owner: nyurik klokan lseelenbinder wipfli

Community

• [x] The new repo has been announced in the #maplibre OSMUS slack channel.
• [ ] The new repo has been announced in the next monthly meeting of the Technical Steering Committee.
• [ ] The new repo has been announced in the @maplibre twitter.

[hactar]

I'm seconding this proposal. Motivation:

• Apple's SwiftUI is now a well established framework in the iOS developer community. MapLibre is UIKit based, which is of course still fully supported, but Apple recommends using SwiftUI instead since 2023. (See Apple's State of The Union). SwiftUI-DSL brings MapLibre into the SwiftUI world natively.
• The framework is passed its early stages of development. https://hudhud.sa/en is using it in its beta app already, the official City of Vienna App (https://apps.apple.com/at/app/stadt-wien/id1014988960?l=en-GB) will be switching to SwiftUI-DSL in the upcoming months. You can't do 100% of what you can do in MapLibre yet, but it already covers enough to create many different types of production ready apps.
• The framework's concept is similar to Apple's SwiftUI MapKit (https://developer.apple.com/wwdc23/10043), so SwiftUI MapKit developers will feel more "at home" with SwiftUI-DSL.
• There are currently 4 active developers, under the official MapLibre umbrella this framework might attract contributions from further developers to speed up feature implementation.

[Archdoog]

I'll add my 👍 and plus 1 to all the motivations and reasoning from @ianthetechie & @hactar.

One additional reason:

This repository is a great proof of concept for approaching a SwiftUI first maplibre-native swift-c++ interop. Meaning we can use the top level SwiftUI architecture, design and how we incrementally built it to approach the next generation of mapblire-native with direct swiftui to c++.

[birkskyum]

I'm approving this. I think it looks great.

Regarding naming, it might be more consistent to go with maplibre-native-swiftui-dsl (or maybe even without -dsl), to align with i.e. maplibre-native-qt.

[ianthetechie]

Thanks!

Your naming suggestion sounds good to me @birkskyum.

I'll update this ticket as we work through the checklist items (might take a few weeks between other stuff; PRs welcome of course :D).

[louwers]

What are the benefits vs downsides of onboarding this repository under the MapLibre organization? From my perspective:

Benefits:

• It might be easier be easier get buy-in to use it in some shops when it is officially a part of MapLibre. So onboarding it will likely attract more users and contributors, which will help mature the project further.
• When people ask what our SwiftUI story is, we will be able to tell people to use this MapLibre project, instead of that Stadia Maps project.

Downsides:

• If we onboard this library, we are somewhat buying into the suboptimal setup of having a wrapper library on top of our creaky Objective-C iOS library.
• This is a pre 1.0.0, experimental project. We should be bold when it comes to embracing experimental projects (e.g. maplibre-rs), but in my opinion only when they stand to greatly improve the status quo. I would personally much rather see MapLibre support a new iOS SDK written from the ground up in Swift. Then our SwiftUI story would be: we're working on a new iOS SDK from the ground up, in the meantime: use this wrapper from (hosted by) Stadia Maps...

[ianthetechie]

If we onboard this library, we are somewhat buying into the suboptimal setup of having a wrapper library on top of our creaky Objective-C iOS library.

I agree that it is not necessarily optimal wrapping the old Obj-C (+ UIKit) base. However, I do not think that either Obj-C or UIKit are going away. Obj-C is not inherently bad.

I would personally much rather see MapLibre support a new iOS SDK written from the ground up in Swift. Then our SwiftUI story would be: we're working on a new iOS SDK from the ground up ...

I think that what needs "fixing" the most (aside from major perf issues or crashes) is the public APIs. These were inherited from the Mapbox project, and we all know the annoyances, hidden footguns, etc.

Rewriting is Swift is something I support, but I think an incremental transition is a far more realistic goal than a ground-up rewrite. The main goals for such a rewrite would be improving maintainability, attracting new contributors, and making it easier for developers to use.

(Aside: Swift-C++ is also still very new, so it's an open question whether the timing is right for a pure Swift rewrite, but that's for another thread.)

But before we can consider rewriting major chunks in Swift, we need to figure out what the improved public API should look like. The SwiftUI DSL project exists specifically to work toward this goal. Our approach of building on top of the existing library does a few things:

• Figure out the UIKit <-> SwiftUI interop story in the context of real production apps; I doubt UIKit support is going away, so we need to figure this out anyways
• Experiment with better "swift-y" interfaces to MapLibre APIs (specifically styling, layer specification, expressions, etc.); for anyone not very familiar with the project, it's worth noting that these are not specific to SwiftUI, and you could use these in a UIKit app as they are in a separate module

Building on top of the existing library allows us to focus on these goals in isolation. The things we learn there will inform public API evolution in MapLibre Native. There are tradeoffs, but I believe the benefit of being able to make changes quickly in a light wrapper will outweigh the drawbacks. API design is hard, and getting it into the hands of users in "real" apps is the quickest way to identify pain or pleasure.

Fun tech discussions aside, the main reasons to host it under the MapLibre org are better visibility (-> more user feedback) and improving the public image of MapLibre as innovating and trying to integrate with these newer UI paradigms (which most are sadly not).

in the meantime: use this wrapper from (hosted by) Stadia Maps...

I'm also fine with that of course ;) But I think we're all agreed on the benefits of hosting this under MapLibre.

[ianthetechie]

Discussed in the Native TSC meeting today and all interested participants agreed to proceed.

@nyurik can you give the second board sign-off and we'll then work through the rest of the onboarding? :)

[ianthetechie]

Ok; sorry for the delay on this, but I just did all the remaining admin work that's necessary pre-merge (can enable funding at the repo level once it moves orgs).

Can someone remind me what the next steps are to properly transfer the repo?

[louwers]

@ianthetechie You should give owner rights to one of the board members, then they can do the transfer.

[ianthetechie]

Ahh ok! @lseelenbinder should have access ;)

[lseelenbinder]

I just transferred.