[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:

• More comprehensive C linting

  • I did some initial exploration regarding Clang and clang formatting. Getting this over the finish line would be a major milestone, as currently we only use cppcheck which only captures a fraction of our C style and formatting needs.

• Compiling Node.js native add-ons pre-push

  • We can update our Git pre-push hook to not only compile C examples and benchmarks (as we already do), but to also compile any native add-ons. This will ensure that (a) native add-ons compile and (b) native add-ons are compiled prior to running unit tests as part of the hook.

• Compiling and running C markdown code blocks.

  • Currently, we run JavaScript code blocks in Markdown files as part of our pre-push Git hook. It would be good if we could do the same for all of our C Markdown examples. Note that this would likely entail that we'd need to add a new configuration in our manifest.json files specifically tailored to running C documentation examples, as documentation may have different dep requirements than benchmarks, examples, and compiling an add-on.

• C doctesting

  • Would be nice to extend doctesting to C documentation and examples, similar to how we perform doctesting on JavaScript JSDoc examples.

• Enable doctesting and linting of index.js files

  • This would help to catch documentation bugs stemming from copy-paste errors. It is not uncommon for us to have omitted changes in index.js files, especially around updated return values.

• More robust linting and doctesting of TypeScript declaration files

  • Currently, our linting of TypeScript declaration files is limited. It would be great to more comprehensively lint these files by applying more ESLint rules. Even better would be extending doctest support to these files.

• manifest.json linting and validation

  • Incorrect manifest.json configuration is a common source of bugs, especially their formatting and included dependencies. It would be good to add additional utilities similar to what we do for package.json files for validating and auto-formatting manifest.json files.

• /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.

[kgryte]

Update: Based on feedback received elsewhere, I've updated the OP with additional ideas.

[batpigandme]

Possibly related to @kgryte’s suggestion re.

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

Have we thought about more widespread use of a formatter/styler/autofix solution for linting errors?

I know many of the extant tools are tied in to specific IDEs, and perhaps there’s an added challenge because so many languages are involved. But, that said, lint errors arise both as stdlib-bot issues, and in PRs (so convert to maintainer time usage).

If interested, I could look into this more closely.

Inspo includes styler (an R package for enforcing tidyverse or custom style guide rules), which has pretty extensive third-party integrations so you can use it in various IDEs, as a git pre-commit hook, GHA workflow, command on a PR, etc.