Simplify contribution

[aminya]

Could you please simplify contributing to this project?

Some of my suggestions:

• reducing the number of requirements
• simplifying PR template
• automating the doc and readme generation from JSDoc instead of the need for copy pasting them in so many places
• Reduce the amount of docs that people should read. In Add a TLDR for cloning #385 I added a TLDR that could replace the whole Contributing.md.
• The code of conduct is usually only relevant when someone violates it so there is no need to keep it in the templates
• Fix RFC: reduce the time it takes to clone the repository #373

I wanted to add a simple denounce function in #374 to this repository but there are so many requirements which makes it hard to contribute to this project.

[kgryte]

@aminya Thanks for reaching out.

While I agree that making the contribution process as easy and straightforward as possible is a desirable goal and that we thus far fall short of that goal, I do think that the situation is more complicated and nuanced than your suggestions suggest.

1. Requirements: if you are referring to development requirements, such as dependency installation, etc, this is hard to simplify, as we need to address multiple different use cases and package types. For example, this library focuses heavily on numerical computing and needs to test against other languages and libraries. And unfortunately, being able to do so requires sometimes relatively complicated local build setups.

   If you are referring to contribution requirements, such as the checklist in the PR template, we essentially have to (a) ensure legal compliance and (b) minimize our time addressing duplicate issues given our limited bandwidth. For checklist items such as filing an issue before submitting a PR, especially feature PRs, the reason we do this is to ensure that contributors do not waste time making a contribution which either does not satisfy project requirements or needs design input. For feature requests, it is possible (or even likely) that we may have already considered such a feature and either have particular reasons for not already doing so (such as technical complexity) or some design iteration needs to take place. While I recognize that this introduces an initial barrier to contribution, especially compared to one-off packages on npm, I also think that aligning on design up front, even for comparatively small API surfaces, produces both better outcomes and faster results.

2. PR template: agreed. GitHub is currently beta testing a template feature which should allow us to simplify the PR and issue templates. So I'd expect our templates to change as soon as this feature is public.

3. Doc generation: unfortunately, this is not possible. Notably, the docs for source code, the REPL, README, etc, all cater to different use cases and audiences. While a fair amount of overlap exists, each document presents its own unique set of requirements. This is especially true for mathematical functions which may have TeX equations and figures in the READMEs, algorithmic details in the source code (JSDoc), REPL specific examples and notes in the repl.txt, and more streamlined type annotations and comments in the TypeScript declaration files. We looked into automation some time ago and walked away without any good universal solutions.

4. Contributing.md: unfortunately, Add a TLDR for cloning #385 does not replace all of this document, especially for running tests, examples, and benchmarks. Our contributing document is not too dissimilar from the Node.js contributing document for pull requests. This project is of a similar size and scope, with extensive tooling exposed to facilitate development. Add a TLDR for cloning #385 does not elude to any of that, which is fine for those familiar with the project, but far too little for those who are not.

5. CoC: linking directly to the Code of Conduct from the templates is common elsewhere and is particularly so when contributors have to sign CLAs before submitting contributions. We feel it is important to communicate very explicitly project expectations concerning conduct on the project's public forums and other contributors.

6. Clone time: as discussed on RFC: reduce the time it takes to clone the repository #373, there are workarounds, including limiting clone depth, which is something we suggest. The repository size is comparable to other large numerical computing libraries/languages, such as NumPy and Julia.

Regarding #374, we definitely appreciate your contribution! And I certainly cannot fault you for feeling like the requirements are too onerous. But at the same time, this project, in toto, is not the same as contributing to a 100 line micro-package, and, as such, is going to naturally impose certain requirements and present a need to educate contributors regarding project tooling, setup, and expectations in order to ensure that both contributors and maintainers are aligned and working toward mutual benefit.

All this said, I am definitely open to additional suggestions. For example,

• we could provide a "cheatsheet" of sorts for all the common project commands.
• we could provide more tailored guides for different package types (e.g., math vs ndarray vs utils, etc).
• we could provide more scaffolding tools, so that a new contributor could clone and run a single command which then walks through various prompts and auto-populates package files (akin to Yeoman generators).
• ...

Thanks again for reaching out. I know that the above is probably not the answer you were looking for, but hopefully it provides a bit more context and nuance and runs counter to the idea that we're intentionally trying to make contributing to the project as difficult as possible! 😅

[aminya]

I created this issue to help the project gain more contributors. The decision is up to you.

This is all you need, if you are concerned with stylistic/legal/moral/political/etc things related to contribution. Adding more checkmarks doesn't help.

[kgryte]

PR template simplified in 102cf13.

[kgryte]

Most the concerns raised in the OP have now been addressed, except for doc generation which is not possible atm given varying use cases and audiences.

If there are additional concerns/suggestions, they can be raised in a subsequent issue.