[RFC]: improving the stdlib developer development experience

[kgryte]

Description

This RFC is a brainstorm of sorts intended to kickstart and organize a discussion around aspects of the stdlib developer development experience which could be improved.

While we have invested considerable time and resources in automation and tooling, gaps still exist, and we can do more to reduce the initial barrier to first contribution. The benefit of continuing to invest in automation and tooling is to stdlib's benefit as it should allow faster development, a smoother onboarding experience, and reduced core developer burden.

Some initial ideas include:

• /stdlib command that core devs can use to run ESLint autofix for selected lint rules

  • For example, we don't enforce uniform spacing inside parentheses and brackets, but we are usually consistent. The idea here would be to turn on enforce spacing for PRs by external contributors so that everything gets uniformly formatted as a starting point.

• Windows development guide

  • New contributors on Windows still face significant hurdles, as we don't have any documentation tailored to their situation. Namely, their need to use the Windows Linux Subsystem in order to be able to use Make, which is the backbone of our tooling.

• A lint-pkg recipe

  • We have various lint rules for linting particular file subsets (benchmarks, source files, examples, tests, etc), but we don't have a single command for linting everything in a package. In short, this recipe would allow specifying a package path filter and then pass that along to the various specialized commands.

• Tutorials/how-to guides for creating new packages

  • Videos/screencasts/docs are needed to better allow new contributors to go from zero to hero. Seeing a core dev create a new package from scratch would be highly beneficial, as core devs can narrate what they are doing and why.
  • Project make commands take some getting used to, so having a dedicated tutorial/guide would go a long way toward getting new contributors comfortable with using our tooling.

• Cookiecutter tooling

  • We can do more to help scaffold new packages/files. I personally have a collection of snippets which helps me quickly add tests, license headers, and more. This sort of thing has been talked about internally for some time, but has always proven a bit tricky to pull off.

• A more streamlined local dev setup process

  • A developer should be able to just clone and run, say, make dev-setup, which then

    • installs Node.js to a local folder
    • installs node modules dependencies
    • installs certain dev deps (e.g., EditorConfig, shellcheck, etc)
    • initializes Git hooks
    • verifies local setup

• More comprehensive docs/tutorials linking together the dev setup, REPL text guide, doc testing, benchmark authoring, Git commit message conventions, and more.

  • Currently, these are all scattered and don't form a single story for how all the pieces come together.

• Command-line workshopper

  • An interactive command-line workshopper (similar to the Node school framework in the olden days) which walks a contributor step-by-step through creating a new package and auto-opens guides in a local web browser, etc.

Related Issues

None.

Questions

• What other things can we do to improve the developer experience? Feel free to leave comments below.

Other

No.

Checklist

• I have read and understood the Code of Conduct.
• Searched for existing issues and pull requests.
• The issue name begins with RFC:.

[Snehil-Shah]

@kgryte Another small addition that I can think of is making a devcontainer.json configuration that can spin up instant dev environments with all the initial setup done.

This configuration can be used by GitHub Codespaces to create an instant dev environment (tailored to stdlib) running entirely on the cloud with zero system requirements.
This can also be used to quickly set up local dev environments using docker and VSCode dev containers.

These containers can further be configured to pre-install VSCode extensions in VSCode or GitHub Codespaces, and can be used to install tools for formatting, linting, etc. requiring zero input from the developer

[kgryte]

@Snehil-Shah That is a good idea. We originally looked into GitHub codespaces, but IIRC ran into problems due to the size of the project. It would be worth revisiting, however, to see if things have improved.

[Snehil-Shah]

@Snehil-Shah That is a good idea. We originally looked into GitHub codespaces, but IIRC ran into problems due to the size of the project. It would be worth revisiting, however, to see if things have improved.

Just FYI, I am using GitHub Codespaces for contributing to stdlib and it's pretty smooth so far, setup took like 3 mins (make install).

[Pranavchiku]

Hey @Snehil-Shah would you mind documenting the steps in a gist and post the link here? We'll be happy to iterate and improve it.

[Snehil-Shah]

Hey @Snehil-Shah would you mind documenting the steps in a gist and post the link here? We'll be happy to iterate and improve it.

Hey, there are no steps needed for initial development in particular, Codespaces comes with a Linux system with node.js and make without any configuration. I just created a codespace and ran make install and make init and done. But as mentioned in the development guide, there might be many other dependencies that are not needed directly for day to day development as mentioned, but you can configure them using a devcontainer.json configuration.

[muni106]

hi @kgryte i think that first of all it would be a great idea to containerize the application, to isolate project's dependencies from the host machine, preventing conflicts and ensuring a clean environment.
This would offer a complete control over the environment by defining a container image with specific tools and libraries.
Last but not least this approach will offer a great scalability.

With this i don't mean that using github codespaces is a bad idea, on the contrary it would be great after the containerization of the project to integrate docker container within codespaces, offering a great experience with both local development and cloud development.

In conclusion i can help with this setup if you think it's a good idea

[uditrajput03]

hi @kgryte i think that first of all it would be a great idea to containerize the application, to isolate project's dependencies from the host machine, preventing conflicts and ensuring a clean environment. This would offer a complete control over the environment by defining a container image with specific tools and libraries. Last but not least this approach will offer a great scalability.

With this i don't mean that using github codespaces is a bad idea, on the contrary it would be great after the containerization of the project to integrate docker container within codespaces, offering a great experience with both local development and cloud development.

In conclusion i can help with this setup if you think it's a good idea

Yes this seems to be great as it Is must for any project to have a container to facilitate developer.

[kgryte]

As a quick update, @Planeshifter added support for launching devcontainers: https://github.com/stdlib-js/stdlib/tree/develop/.devcontainer.