Skip to content

[RFC]: improving the stdlib developer development experience #1378

Open

Description

@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:.

Activity

  1. added
    Help WantedExtra attention is needed.
    RFCRequest for comments. Feature requests and proposed changes.
    ToolsIssue or pull request related to project tooling.
    priority: NormalNormal priority concern or feature request.
    on Feb 25, 2024
  2. Snehil-Shah commented on Feb 25, 2024

    @Snehil-Shah
    Member

    @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

  3. kgryte commented on Feb 25, 2024

    @kgryte
    MemberAuthor

    @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.

  4. Snehil-Shah commented on Feb 26, 2024

    @Snehil-Shah
    Member

    @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).

  5. Pranavchiku commented on Feb 27, 2024

    @Pranavchiku
    Member

    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.

  6. Snehil-Shah commented on Feb 27, 2024

    @Snehil-Shah
    Member

    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.

  7. muni106 commented on Feb 27, 2024

    @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

  8. uditrajput03 commented on Mar 7, 2024

    @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.

  9. kgryte commented on Apr 17, 2024

    @kgryte
    MemberAuthor

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

  10. kgryte commented on Jun 29, 2025

    @kgryte
    MemberAuthor

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

  11. pinned this issue on Jun 29, 2025
  12. batpigandme commented on Dec 15, 2025

    @batpigandme
    Member

    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.

  13. kgryte commented on Dec 15, 2025

    @kgryte
    MemberAuthor

    @batpigandme We currently support a lint-autofix command, but this is currently limited to a specific subset of lint rules which we are comfortable with ESLint auto-fixing.

    Otherwise, one of our todos is to have, e.g., an ESLint configuration specifically tailored to PRs which is much more aggressive about particular style choices in order to get a PR to a desired baseline.

  14. kgryte commented on Dec 15, 2025

    @kgryte
    MemberAuthor

    @batpigandme As for R auto-formatting, sure, don't see why not, as here we are not particularly opinionated. We currently have https://github.com/stdlib-js/stdlib/blob/develop/tools/lint/r/linter.R for performing basic linting.

  15. kgryte commented on Dec 15, 2025

    @kgryte
    MemberAuthor

    Ditto for Julia and Python (e.g., Black).

  16. batpigandme commented on Dec 15, 2025

    @batpigandme
    Member

    Ditto for Julia and Python (e.g., Black).

    Yeah, I guess I was wishcasting something to the effect of emacs format all (which, I’ve never actually used, but know covers a bunch of file types).

    Or just adding more formatters (e.g. remark formatting when remark lint is run)

  17. batpigandme commented on Mar 11, 2026

    @batpigandme
    Member

    Notes from contributor interviews (Gemini's hot takes):

    Priority Suggestion Frequency
    1 Accelerate the Pull Request (PR) Review Process Contributors repeatedly cited the slow pace of PR merging and the lack of communication on older, open issues as the biggest friction point. Faster feedback from maintainers (Athan and Philipp) is the most desired improvement. 8
    2 Improve Codebase & Package Dependency Documentation A lack of clear documentation on how packages and namespaces connect makes the large repository difficult to navigate. Suggestions included creating a visual dependency tree or a tool to map package dependency chains. 5
    3 Centralize & Clarify Documentation for Conventions Multiple contributors mentioned the need for a single, centralized resource for coding conventions, PR expectations, and style guides to ensure consistency. This also includes documenting the rationale for using C code alongside JavaScript. 5
    4 Streamline Setup, Linting, & Local Testing New contributors struggled with initial setup friction (e.g., Docker, Windows make errors), running JavaScript examples in readmes, and performing general or specific lint/make tests locally. Clearer documentation of make recipes and local testing functionality is needed. 5
    5 Create Video Tutorials for Codebase Navigation There is a high demand for video content—not high-production, but short guides—to demonstrate how to navigate the complex codebase and illustrate implementation methods and conventions. Recording office hours was specifically suggested to capture this "tacit knowledge." 3
    6 Enhance Website UI and Search Functionality Suggestions included improving the documentation website's user interface (UI) and fixing the accessibility of the search bar, which was described as "literally invisible" in the documentation. 2
    7 Refine Onboarding & Progression Guidance New contributors struggle with knowing where to focus their efforts after completing initial "good first issues." Guidance is needed on how to transition from trivial tasks to more complex, next-level contributions. 2
  18. batpigandme commented on Mar 12, 2026

    @batpigandme
    Member

    Adding another todo (might deserve its own issue), but, given that Markdown files have their own linting rules (the remark plugins), I think it makes sense for there to be a Markdown style guide. I realize this is partially covered by the text style guide, but if we're looking to do a one-to-one rule-to-enforcement linking thing (per @kgryte and my discussion yesterday), I think it'll be nice to have this structure.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Help WantedExtra attention is needed.RFCRequest for comments. Feature requests and proposed changes.ToolsIssue or pull request related to project tooling.priority: NormalNormal priority concern or feature request.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions