Checking out a specific branch or tag is not documented about build-tools HOT 8 CLOSED

@hardfalcon Thanks for the issue! This is a great callout - in most cases, we encourage everyone to base off of main and then let maintainers backport, but there isn't much documentation for the cases that require branching off of a specific release branch. We'll make sure that more documentation is added 😄

For reference, you can also just use the git checkout command (i.e.: git checkout 26-x-y). But to your point, it's unclear whether or not you should just use build-tools commands and when/where. We'll clarify that in build-tools docs and also in the initial contributing docs here: https://www.electronjs.org/docs/latest/development/pull-requests#setting-up-your-local-environment

If you have any additional pain points that we could improve in the docs, let me know. Thanks!

from build-tools.

Thanks for the quick reply! :)

Please consider that git checkout doesn't really help in many cases, because fixes for stable/older versions of Electron will often be backports of commits from external dependencies, for example in chromium, node, or even dependencies of those. In my specific case, the issues were in two dependencies of node, one of which had actually already been fixed in more recent releases from node's 18.x version branch.

In my specific case, it would have saved me literal days of trying figuring things out if Electron's official documentation on patches contained a concise example like the one from here, augmented by the commands/parameters required to write such a change only for a specific version branch of Electron.

Even without being familiar with the (from my point of view very obscure) tooling that is used to write patches for Electron, it's easy to figure out from past commits trivial changes like minor version updates of dependencies (you can even do that using only Github's web interface), and from there, it's not too difficult to then figure out which version of a specific dependency is used, and to track down the required fix/commit from that upstream repo.

What is excessively complicated and burdensome in my experience is actually testing your change by actually building electron with that change, especially when most of the documentation around Electron's build-tools appears to be written more with people in mind who are trying to build new applications based on Electron rather than people working on changes for Electron itself. Perhaps there should be a dedicated section for the latter in the Contributing section on https:://electronjs.org, and there should definitely be a dedicated section for this stuff in this git repo's readme file.

from build-tools.

Please consider that git checkout doesn't really help in many cases, because fixes for stable/older versions of Electron will often be backports of commits from external dependencies, for example in chromium, node, or even dependencies of those.

I'm not sure what the issue here is? Note that Electron maintainers use build-tools to do backports to older Electron versions on the regular. You simply checkout the older branch and sync:

$ git checkout 26-x-y
$ e sync

especially when most of the documentation around Electron's build-tools appears to be written more with people in mind who are trying to build new applications based on Electron rather than people working on changes for Electron itself.

Quite the opposite, build-tools is geared specifically to working on Electron itself - app developers shouldn't be using build-tools.

Perhaps there should be a dedicated section for the latter in the Contributing section on https:://electronjs.org

The "Contributing" section on the website is for working on Electron itself - the build instructions pretty clearly call out they're for building Electron itself:

Follow the guidelines below for building Electron itself, for the purposes of creating custom Electron binaries. For bundling and distributing your app code with the prebuilt Electron binaries, see the application distribution guide.

from build-tools.

Addressing the title of this issue, there is indeed documentation on checking out a branch or tag: https://github.com/electron/build-tools#building-a-specific-electron-version

from build-tools.

@dsanders11: Oh wtf, how the heck did I manage to overlook that section? I could have sworn that I did a plaintext search on this very page in the browser even several times yesterday for strings like branch, release or version… o_O

Is there a way to have a table of contents at the top of the page, such that the existence of a section such as Common Usage or even the more specific Building a Specific Electron Version isn't lost exactly 1 screen height above the bottom of the page? As it turns out, at some point, I had actually scrolled down all the way in pure despair, and discovered the existence of the Advanced Usage section, but still managed to overlook the Common Usage section right above).

from build-tools.

Is there a way to have a table of contents at the top of the page

GitHub provides a table of contents on the main repo page in the upper left corner.

When viewing Markdown files directly, the button switches to the upper right corner and provides an outline panel on the right side.

from build-tools.

This isn't shown on my machine (1920x1080 resolution, Firefox 119 with menu bar, tab bar and bookmarks toolbar enabled). Even when I open the README.md file itself on Github, that TOC box is only shown for a fraction of a second when (re)loading the page, before it is hidden again. I briefly suspected this might be caused by my ad blocker, but disabling the ad blocker and reloading the page doesn't change the behavior.

from build-tools.

I'm going to close this out since this specific issue is currently documented.

from build-tools.