Repository navigation
Description
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
cppcheckwhich only captures a fraction of our C style and formatting needs.
- 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
-
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.jsonfiles specifically tailored to running C documentation examples, as documentation may have different dep requirements than benchmarks, examples, and compiling an add-on.
- 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
-
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.jsfiles- This would help to catch documentation bugs stemming from copy-paste errors. It is not uncommon for us to have omitted changes in
index.jsfiles, especially around updated return values.
- This would help to catch documentation bugs stemming from copy-paste errors. It is not uncommon for us to have omitted changes in
-
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.jsonlinting and validation- Incorrect
manifest.jsonconfiguration 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 forpackage.jsonfiles for validating and auto-formattingmanifest.jsonfiles.
- Incorrect
-
/stdlibcommand 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-pkgrecipe- 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
makecommands 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
Snehil-Shah commentedon Feb 25, 2024
@kgryte Another small addition that I can think of is making a
devcontainer.jsonconfiguration 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 commentedon Feb 25, 2024
@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 commentedon Feb 26, 2024
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 commentedon Feb 27, 2024
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 commentedon Feb 27, 2024
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 installandmake initand 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 adevcontainer.jsonconfiguration.muni106 commentedon Feb 27, 2024
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 commentedon Mar 7, 2024
Yes this seems to be great as it Is must for any project to have a container to facilitate developer.
kgryte commentedon Apr 17, 2024
As a quick update, @Planeshifter added support for launching devcontainers: https://github.com/stdlib-js/stdlib/tree/develop/.devcontainer.
kgryte commentedon Jun 29, 2025
Update: Based on feedback received elsewhere, I've updated the OP with additional ideas.
batpigandme commentedon Dec 15, 2025
Possibly related to @kgryte’s suggestion re.
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.
kgryte commentedon Dec 15, 2025
@batpigandme We currently support a
lint-autofixcommand, 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.
kgryte commentedon Dec 15, 2025
@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.
kgryte commentedon Dec 15, 2025
Ditto for Julia and Python (e.g., Black).
batpigandme commentedon Dec 15, 2025
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)
batpigandme commentedon Mar 11, 2026
Notes from contributor interviews (Gemini's hot takes):
makerecipes and local testing functionality is needed.batpigandme commentedon Mar 12, 2026
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.