RFC: Developer Experience WG kick off - we want your input!

[beriberikix]

Hi all,

During a BoF session at this year's Developer Summit, several of us felt the need to kick off temporary working group focused on the Developer Experience of Zephyr. Topics that spurred the discussion included Editor and IDE configuration, (ex. what's the VS Code experience?) & CI/CD performance with Github Action.

We're hoping to kickoff our first call soon but we want to collect any initial feedback! We're looking for aspects of the experience you feel could be improved, specific Issues or PRs (ex. #21119), examples of DevExps that you like or anything else that will help in our pre-planning.

Our first task will be to set charter & goals for the group but some examples might be:

• Identify gaps between dev env setup across Windows, macOS, Linux, Docker & VMs
• Toolchain support
• Opportunities for new or enhanced documentation
• Build times

...and a lot more. So we're asking again for your feedback! And stay tuned for more details of when the WG will host the first call.

[beriberikix]

Let me kick things off when some issues that have been referenced:

• VS Code integration VS Code integration #21119
• Improved user interface for devicetree Improved user interface for devicetree (like guiconfig) #29295
• Python venv [slack], Install Python deps in a virtual environment #23979
• macOS support

[galak]

I haven't looked into the details, but if some standard devcontainer is possible.

https://code.visualstudio.com/docs/remote/containers

[dkalowsk]

Not sure if this will help the discussion, but it did provide the prototype framework we have put to use for many of our developers using VSCode. The article was not written by me or anyone attached to the company. https://blog.feabhas.com/2021/01/vscode-dev-containers-and-docker-moving-software-development-forward/

[cfriedt]

W.r.t. macOS support, I think it's imperative that we support native_posix_64.

I started a draft PR working through what is required to make that happen - kind of a brute force method. I don't have tons and tons of time to devote to it, but I can say that it would probably be incredibly useful for a lot of devs.

Currently, need to integrate macholib into scripts/gen_offset_header.py.

#37123

[Thalley]

Regarding VS Code support, we could take some inspiration from how how Particle has provided their SDK and good VS Code integration in their Workbench extension: https://marketplace.visualstudio.com/items?itemName=particle.particle-vscode-pack

Basically by installing this extension, it downloads their SDK and everything needed to build and flash to their devices. Furthermore it provides build and debug tasks in VS Code, as well as templates for creating projects/applications (something that we often hear people asking about in Slack).

This type of (extensive) extension provides a single click (install extension) to be able to use their product, and is something that we could possibly do for Zephyr as well.

[beriberikix]

I agree - but I should first caveat that I was product manager who oversaw the creation of Workbench during my time at Particle (so I'm biased.) For background, we were a fairly early extension creator and we found many bugs, which has long been fixed. Besides those bugs, there were two big challenges:

• We had to build our own package manager for our SDK and dependencies (~3mo+ of eng work)
• The UX of VSC for extensions is purposefully restrictive, so we had to get very creative and still hit limitations

The package manager part was particularly challenging. We wanted to make sure our tools, local compiler, build dependencies, SDK & samples Just Worked:tm:, so we shipped everything, even including XXD for all 3 major OSes.

I think something like that would very much improve the developer experience for those who use VSC and other editors/IDEs. My team unfortunately doesn't have the resource to work on something like that today but we'd love to collaborate with those who might be interested. I'd enjoy building something like that again!

[beriberikix]

From @galak: Establish package distribution strategy

[beriberikix]

Developing on Windows & WSL - lack of USB support.

[stephanosio]

I don't think we will be getting USB support in WSL anytime soon (if ever). There are unofficial hacks to get it sort of working, but they tend to be very messy, unreliable and subject to stop working anytime Microsoft decides to change something internally.

The best solution I've found is to just install the host utilities (e.g. nrfjprog for nRF on Windows) and call them directly from inside WSL -- executing Windows executables from inside WSL can be done by just adding the .exe suffix given that they are available in the Windows PATH (e.g. nrfjprog.exe from WSL shell will call Windows nrfjprog.exe).

For instance, you can alias/symlink nrfjprog to nrfjprog.exe in the WSL in order to make the existing infrastructure (e.g. west flash) call the Windows host utilities, and that has been working quite perfectly for me so far.

[beriberikix]

I do the same but for cloud development :)

I'm still hopeful for USB support! See this exchange.

[beriberikix]

Browser-based environments with Github Codespaces.

[abelNoelleC]

More information on how to integrate west with IDEs (such as Eclipse) would be great!
Multiple pre-defined build configurations, also depending on the board or different applications (configurations).

Also tips on how to set up a good (HW-based & automated) testing environment specific for Zephyr. A central place for the tips & tricks in this area (since it obviously is quite subjective to your needs as well) would be great to have.

These are the ones off the top of my head now :)

[abelNoelleC]

Also different recommended methods to set up CI if you have application code (so not for contributors, but for users of the OS). It can be tricky to figure out how to set this up without making it confusing for the developer, since there will likely be multiple locations you'll get the code from, even if you use a stable release of the core OS. The west workspace and manifest options are great, but it can become quite the puzzle to keep the application code and upstream code aligned, and that you have to import them separately. This becomes even more complicated when you do a mix of application code, and contributions to the project.

I know some documentation efforts have already been made in this area, but I think it would be good to review whether it can be streamlined even more from an infrastructural point of view, not just information/documentation.

[mbolivar-nordic]

I am helpless to resist my tendency to go meta....

I've sometimes been discouraged by the hassle of getting through review and not bothered to post useful advice as pull requests to the official docs. I've also sometimes avoided doing so because the advice was necessarily platform-specific and I couldn't find a place to put it.

Maybe we should have some sort of unofficial wiki where we can put stuff like this? I've seen people use github issues for this and it wasn't a great fit. Maybe using discussions would be better since you can pick an "answer" for a discussion.

But the meta question of a separate place for tips and tricks that doesn't have to jump the hurdles of review might be worth discussing.

[mbolivar-nordic]

But the meta question of a separate place for tips and tricks that doesn't have to jump the hurdles of review might be worth discussing.

@cfriedt @beriberikix I posted #37155 as a potential standard way for people to share modules with each other more easily, maybe to allow people to share examples themselves with less overhead.

The workflow is basically "add this file to your submanifests folder and run west update to get my cool code".

[trond-snekvik]

Great initiative! 👏
I would like to contribute to this effort, both through VS Code support, and in other aspect of the user experience. I have a few items I'd love to talk about in this context that haven't been mentioned yet:

• GitHub Template repositories to supplement or replace the example application repo
  • Showcase various west topologies
  • Include github actions setup?
• Reducing default set of west modules, strategies for reducing initial download size. Addressed in west.yml: add project groups #36981
• More user guides to supplement the current "reference" style of documentation for many modules
• Committing changes made in menuconfig to the prj.conf file
• Language servers for Kconfig and DeviceTree
• IDE support for GUIs for Kconfig, DeviceTree (as mentioned by @nashif), and DeviceTree bindings files
• Improving the documentation writing process and tooling
• VS Code/Emacs/Sublime/Eclipse extensions for other aspects of Zephyr development and usage:
  • West
  • Twister (using upcoming Test API for VS Code)
  • General app development (build, flash, intellisense)
• Menuconfig menu organization (and best practices?)

I wouldn't be able to take on all of these by myself, but I hope we can get some progress on some of these, at least :)

[robwoolley]

These all sound like great projects. Many of them seem to be generally applicable to many open source projects. Notably language servers and GUI tools for Kconfig, DeviceTree, and Menuconfig. It also is directly related to work we are doing in the Memory Footprint and Testing Working Groups. Let me know how we can collaborate.

[cfriedt]

+1 for macOS support :-)

[TSMotter]

• I'd like to be able to download a .pdf manual with all the contents of the online documentation, like a book.
• Maybe translate the docs to other languages? I have no problem in using English, but I think it would be important for the growth of the comunity if we had documentation available in other languages. I make myself available to translate it to PT-BR if it comes to be and interesting addition!

[beriberikix]

There was recently a discussion about PDF generation in #documentation! And I can't remember the plan for localization. @gmarull ?

[gmarull]

Hopefully we'll have PDF docs available soon, I've started working on CI support for them: #37088.

Regarding localization, I'm not aware of any plan for now.

[mbolivar-nordic]

I'm not aware of any plan for now.

I think this is simply not feasible.

[beriberikix]

I'd imagine it wouldn't be feasible as well. While technically possible with Sphinx, it would require a significant re-write of just about everything and a maintenance process & plan. :/

[cfriedt]

Also, going to drop this here and just walk away.

The example module needs lots of love. It should really serve as a template for people to clone, modify, and then call their own. Personally, I think it should be more or less a catch all, and let people remove stuff that they do not need.

1. clone
2. prune out stuff that is not needed
3. re-home / rename
4. push
5. add custom stuff
6. go back two steps & repeat

[mbolivar-nordic]

like a scaffold generator?

Yeah, something like that.

Though you quickly get into people's individual preferences for what the "Right Thing" is, which gets sticky. Developing what little we have in the example application was the result of several months of sometimes contentious arguments about what was "best".

That relates to my earlier comment about having a place for people with opinions to just share them and just let user momentum decide what "best" is.

[trond-snekvik]

+1 for a generator-like approach. This could also be applied to board definitions and (potentially) driver creation.

[gmarull]

+1 I think a sort of "create-react-app" would be a great feature. The tool could interactively ask user when creating the app: add custom board? Add custom driver boilerplate? Etc.

[stephanosio]

+1 for code generator approach. maybe the generator itself can be Kconfig based so users can either -DCONFIG_SOMECONFIG=val in command line or interactively specify configs in menuconfig.

[beriberikix]

Since we're brainstorming, it would be nice if the scaffold generator had a means to support multiple outputs projects (like mentioned) in a structured way. Look at all the generators in the Yeoman ecosystem.

We don't need a overly complicated generator design but the goal of having more than one, and possible user created ones would be nice. Coming more recently from the Go world, the built-in Template system is used for much more than HTML and I imagine that there are several comparable engines in Python. Being able to input say a jinja2 file as the scaffold template would be clean way to add extensibility and reuse a well-designed templating system.

[Thalley]

One thing that has really been a thorn in my side since I started with Zephyr is how code review is done.

The Zephyr process of creating a commit, and then using git commit --amend and git push -f works terrible with the code review of Github that is incapable of showing different versions of the same commit/PR when it is force updated.

I saw someone experimenting with https://reviewable.io/ as a an alternative to the Github code review. I think looking into other (better) ways of reviewing PRs is something that we should (continue to) pursue.

[marc-hb]

The Zephyr process of creating a commit, and then using git commit --amend and git push -f works terrible with the code review of Github that is incapable of showing different versions of the same commit/PR when it is force updated.

Indeed Github is not git, its preferred review model is "fixup-based" instead. It's not as extreme as "considering rebase harmful" but pretty close. For the record I violently disagree with this article, I think the "history of the history" is one of git's best features. Github does not care about that extra dimension.

This unfortunate mismatch is documented here: #14444 (comment)

I don't think anything can be done about it, I mean I don't expect github to evolve for a small minority of its users.

[Thalley]

I don't think anything can be done about it, I mean I don't expect github to evolve for a small minority of its users.

It has been an open issue for some time: isaacs/github#999

I don't think we can expect Github to change it either - At least I am not aware of any intention to do so either. Using an 3rd party solution (such as reviewable) might be our best chance of doing something ourselves.

The "fixup-based" approach with a final squash would require that, once the PR has been approved and is ready for merge, the author of the PR does a local squash and force-pushes that (basically returning to the "regular" force-push approach, and messing up references to specific pieces of code from comments), as contributors are not allowed to use the Github web UI to squash and merge in order to properly update the git message. Thus I don't think that the "fixup-based" approach would work for Zephyr, unless we skip the final squash, but then we end in a situation where we cannot reliably use git bisect as nor all commits will work as intended (i.e. if we have a lot of small "fix comment" commits.