elementary
Migrate to Gtk4
Problem
Currently the docs are centered around Gtk3, which is okay but Gtk4 is available and we should probably be encouraging developers to build with that instead so their apps are more Wayland-ready
Proposal
Migrate everything to Gtk4 instead of Gtk3
Prior Art (Optional)
No response
Flatpak Platform 7 does include Gtk4, but for ease of development maybe we should make sure we don't publish before OS 7 is released?
As long as we are going through all code snippets in the docs repo, would it make sense to reorganize the vala-lang/examples as well?
For me at least it makes it easier to write the documentation if I have an example app that I can run and verify the behavior I'm describing. This would mean adding example apps for the documentation pages which currently lack them, such as Launchers and Notifications pages.
Also, the current examples repo separates example apps into different branches. I suggest creating a mono-repo and separating different apps into sub-directories. That would make parallel updates of several apps (such as Gtk3 to Gtk4 migration) easier to both implement and create pull requests for.
With these 2 points in mind would it make sense to create a new examples repository, under elementary organization? Or perhaps even making a sub-directory in this repo? I'm not sure if that would somehow interfere with GitBook tough.
@Antolius totally agree it can be a lot easier to write good docs with a good code sample branch to accompany it. It would be great to have example branches for every docs section.
The biggest problem with a mono repo imo is that examples should be not just Vala code samples but also include any other files for the section like metadata, build system, etc. So it would be much less clear and compartmentalized than branches where once you check out a branch you only see exactly what is relevant to that example and nothing extraneous. We should optimize for ease of understandability for the audience over ease for maintainers
Usually we also don't want to be making lots of updates at once. It's much better to make several smaller pull requests that can be more quickly and easily reviewed. Large branches can often sit because they take more effort to review and sometimes changes that could be merged sooner get held back because another part of the pull request needs fixing
I'm not super opposed to having the code examples repo be under the elementary org, but I figured it would get more exposure or be more generally useful under the Vala org. I think it would interfere with GitBook to try to combine it with the docs repo though
Ok, then I'd say it makes more sense to stick with the current example repo. We just need a little bit of PR juggling for this gtk4 migration.
We can open separate pull request with gtk4 ports for all existing branches. And then we can add new branches with fresh gtk4 code for topics which are not currently covered. I'm just not sure how to do pull requests for those new branches though.
And for the docs repo itself, do we also want separate PRs for each page, or will a single PR suffice? Technically, the code snippets themselves will already have been reviewed through example repo PRs, so single docs PR might be OK in this case.
(P.S. I'm sorry if I'm overthinking this. I'd like to help out with this documentation update, but I don't want to go into a wrong direction with it.)
@Antolius I could make orphan branches as needed on the examples repo. Just let me know 👍
I would personally do different branches on the docs repo just in case code example A is approved but code example B needs changes. Then we could still merge the related docs branch at the same time as the code example update without having to wait for all of the code example branches to be approved