Explanation of ESP-IDF branches?

[vonnieda]

Hi all, something I've never been quite clear on: What is in the intention for each branch of ESP-IDF, and in addition, what branch should one use for production firmware?

The Getting Started guide has you clone from master, but master seems to include changes that have not yet been released into an official release.

I ask this because I am trying to figure out how to switch to a more stable branch. I am currently using a commit from April 24th in master because it contained a bug fix I needed, but if I try to switch to release 3.0.2 it seems that that bug fix has not been ported. It does appear in 3.1-beta, but I'm not interested in using a beta for my production firmware.

So, can someone clarify a best practice for which branches to use, and maybe explain how one should think of master?

Thanks,
Jason

[fly135]

I'd like to know about this as well. Also why does the forum section on the SDK not get any updates with this kind of info.

John A

[ESP_Sprite]

At the moment of writing, we have the following releases, that may or may not also be git-branches in our repo on Github:

- Master branch. This is what they call 'bleeding edge'; meaning that as soon as us devs have completed a feature or bugfix, it is automatically checked by our CI setup (to see if we didn't accidentally break anything) and if that succeeds, it's pushed to Github. While this branch is perfectly functional most of the time, sometimes bugs sneak through as no full manual testing is done.

- Original stable release, in this case this would be 3.0.0. At a certain time, we decide to release the features in the master branch as stable. We split off master into a separate branch and our dear QA team tests the hell out of that to make sure everything, including the things that are hard to test in a CI setup, works as intended.

- Bugfix releases. This is fairly new, and we're now at 3.0.2. Every now and then, after the release of a stable release, we still find that there are some small things wrong with it that our tests didn't cover. If we are convinced these issues can be fixed by something that only affects a small part of the code. We integrate these bugfixes in an internal tree, and on a regular basis (I think it's monthly) we test and release these as a bugfix release. The intention is that you can switch from a stable to the latest bugfix release without needing to change your code at all.

- Furthermore, when we're making a new release, you'll see -RC (Release Candidate) branches. These are 'advance releases' of the next stable release: any API changes and feature additions that we want to have in the final stable are already in there, but there may still be a bug or two here and there. If you develop a library or something else others use, you can use this to essentially make it compatible with the next stable release as soon as it comes out.

I think we do post announcements for new releases here on the forum as well, I know Angus did this for the 3.0.x releases at least.

Also, a note on versioning: we follow a semantic versioning scheme; esp-idf versions are versioned with an x.y.z triplet (e.g. 3.0.2). The meaning of this is:
- X changes (e.g. 2.1 -> 3.0.0): API changes are very probable (because e.g functions marked as deprecated have been removed). You may need to change things in your code to make it compile with the new version. Changes like this also usually add a fair slew of new features.
- Y changes (e.g. 2.0 -> 2.1): No API changes, in theory your code should compile as-is. Underwater, behaviour may have been re-factored, though, so it's a good idea to test if your code still works as expected. Changes like this also come with new features.
- Z changes (e.g. 3.0.1 -> 3.0.2): Bugfix release. No API changes, no changed behaviour (except where the behaviour caused the bug that's now fixed). You should be able to switch to this version with your program working exactly the same (aside from the fixed bugs).

[vonnieda]

At the moment of writing, we have the following releases, that may or may not also be git-branches in our repo on Github:

Thanks for the response ESP_Sprite! So, given that, a few questions and suggestions:

1. Does it make sense for the Getting Started guide to continue to reference master? Or should it be maybe changed to a stable release? I ask because when I started my project, I started with master, and then realized I needed to "downgrade" to 3.0 to get a stable release after master became unstable.

2. It would be helpful if this information was in the README for ESP-IDF, or in the documentation.

Thanks,
Jason

[ESP_Dazz]

1. Does it make sense for the Getting Started guide to continue to reference master?

You can change the version of the docs at the bottom left hand corner of the page.

[vonnieda]

1. Does it make sense for the Getting Started guide to continue to reference master?

You can change the version of the docs at the bottom left hand corner of the page.

Hi ESP_Dazz - I'm not referring to the version of the docs. I'm referring to the Get ESP-IDF in the Get Started Guide. It instructs people to clone master: https://esp-idf.readthedocs.io/en/lates ... et-esp-idf

I'm wondering if it would be better to instruct people to clone a stable release so that they don't pick up untested code.

Thanks,
Jason

[ESP_Sprite]

You are right, it may be a good idea to note the fact that master is bleeding-edge plus a note to check out stable instead there.

[fly135]

Question about the difference between preRelease v3.1 beta1 and v3.02 release...

In the v3.1 beta-1 the known issues lists.... "Wi-Fi performance is not good when signal is weak"

Is this also an issue in v3.02, or is it something new that snuck in to the newer code? I'm trying to make the leap from v3.1-dev-449-gc97b8756-dirty to something newer. v3.02 release is much newer, but going from a v3.1 to a v3.02 seems like going backwards. However v3.02 is the latest "release" code.

John A

[ESP_Angus]

In the v3.1 beta-1 the known issues lists.... "Wi-Fi performance is not good when signal is weak"

Is this also an issue in v3.02, or is it something new that snuck in to the newer code? I'm trying to make the leap from v3.1-dev-449-gc97b8756-dirty to something newer. v3.02 release is much newer, but going from a v3.1 to a v3.02 seems like going backwards. However v3.02 is the latest "release" code.

This is only a known issue in v3.1-beta1. I would recommend moving to v3.0.2 unless there is a feature in v3.1 that you are relying on (the 3.1-beta1 release notes have a list of new features).

A section about the different versions (and how to choose which version to use) will be added to the IDF Programmers Guide soon (very similar to the advice ESP_Sprite posted, above).

[fly135]

I would recommend moving to v3.0.2 unless there is a feature in v3.1 that you are relying on (the 3.1-beta1 release notes have a list of new features).

This is the only thing i see in 3.1-beta1 I need. So I will move to v3.0.2 for now.

Bootloader refactoring, configurable factory reset and test app trigger functionality

John A