docs: form an official process/policy for updating our Zig version #1122

New issue

Closed

opened 2023-11-30 18:20:25 +00:00 by emidoots · 1 comment

emidoots commented

2023-11-30 18:20:25 +00:00

(Migrated from github.com)

Context

Today we hold PRs like https://github.com/hexops/mach-glfw/pull/32 and don't merge them until we're ready to upgrade all Mach projects to the latest Zig version.

Sometimes upgrading to the latest Zig version is easy, other times it can be more complex. For example, many times we can complete this in all ~40 projects we have in under a day - but sometimes more extensive changes have been made to Zig and we need to put in more time.

In cases where we know it will take more time to upgrade, users of standalone libraries often send PRs like https://github.com/hexops/mach-glfw/pull/32 wanting to use the latest Zig version .. but we can't merge those until we're ready to upgrade all our projects, otherwise they will frequently be supporting different Zig versions which makes developing, testing, and in general using them more difficult - especially by normal Mach users.

For example, someone may stumble across mach-sysaudio and decide to try it, then try to use mach-flac to decode FLAC audio files.. only to find they don't support the same Zig version yet because we're in the middle of an upgrade. Using 'the older version' isn't really a great option either, as then you are unable to easily send PRs to fix real issues unrelated to upgrading Zig.

Aspiration

Define a specific time/date, e.g. on the 1st of every month, or every 2nd or 3rd month, during which we begin the process of updating our Zig version in every project.
We start at the bottom of our dependency tree and work our way up.
We articulate how this impacts users of standalone libraries, mach core, and mach engine - in different ways.
We describe how a mach engine user can look at https://github.com/hexops/mach/blob/main/.zigversion to find a supported Zig version for that version of Mach, and how a mach-core user can do the same by looking at github.com/hexops/mach@9250310c4a/build.zig.zon (L18-L21)
We write all of this down, on https://machengine.org/about/ somewhere so that we can easily link people who encounter issues to the solution to their problem.
Update machengine.org with instructions for which Zig version to use in every 'getting started' tutorial, e.g. https://github.com/hexops/machengine.org/pull/19

## Context Today we hold PRs like https://github.com/hexops/mach-glfw/pull/32 and don't merge them until we're ready to upgrade all Mach projects to the latest Zig version. Sometimes upgrading to the latest Zig version is easy, other times it can be more complex. For example, many times we can complete this in [all ~40 projects we have](https://wrench.machengine.org/projects/) in under a day - but sometimes more extensive changes have been made to Zig and we need to put in more time. In cases where we know it will take more time to upgrade, users of standalone libraries often send PRs like https://github.com/hexops/mach-glfw/pull/32 wanting to use the latest Zig version .. but we can't merge those until we're ready to upgrade _all_ our projects, otherwise they will frequently be supporting different Zig versions which makes developing, testing, and in general using them more difficult - especially by normal Mach users. For example, someone may stumble across mach-sysaudio and decide to try it, then try to use mach-flac to decode FLAC audio files.. only to find they don't support the same Zig version yet because we're in the middle of an upgrade. Using 'the older version' isn't really a great option either, as then you are unable to easily send PRs to fix real issues unrelated to upgrading Zig. ## Aspiration * Define a specific time/date, e.g. on the 1st of every month, or every 2nd or 3rd month, during which we _begin_ the process of updating our Zig version in every project. * We start at the bottom of [our dependency tree](https://github.com/hexops/mach/issues/1071) and work our way up. * We articulate how this impacts users of standalone libraries, mach core, and mach engine - in different ways. * We describe how a mach engine user can look at https://github.com/hexops/mach/blob/main/.zigversion to find a supported Zig version for that version of Mach, and how a mach-core user can do the same by looking at https://github.com/hexops/mach/blob/9250310c4a3e229e6da47b5f8bd60b7168db1a86/build.zig.zon#L18-L21 * We write all of this down, on https://machengine.org/about/ somewhere so that we can easily link people who encounter issues to the solution to their problem. * Update machengine.org with instructions for which Zig version to use in every 'getting started' tutorial, e.g. https://github.com/hexops/machengine.org/pull/19

👍 7

emidoots commented

2024-01-07 08:20:38 +00:00

(Migrated from github.com)

Helped by new issue template: https://github.com/hexops/mach/issues/1135