docs: add a contributing FAQs document

[aayush0325]

Description

What is the purpose of this pull request?

This pull request:

• adds an initial doc with frequently asked questions by first time contributors

Related Issues

Does this pull request have any related issues?

No.

Questions

Any questions for reviewers of this pull request?

No.

Other

Any other information relevant to this pull request? This may include screenshots, references, and/or implementation notes.

No.

Checklist

Please ensure the following tasks are completed before submitting this pull request.

• Read, understood, and followed the contributing guidelines.

---

@stdlib-js/reviewers

[aayush0325]

kindly check if we need to add more make commands other than the ones already present in the doc, i was conflicted about whether to add one for generating polynomials via evalpoly.js

[kgryte]

@anandkaranubc I'm curious if you have any additional thoughts on FAQs that we should include given that you've also been doing a fair amount of code review.

[aayush0325]

not sure if i've taken the correct approach for adding images in this doc, currently i've just copy pasted the screenshots, this way the images are visible when we open the doc on a browser but if i try to preview this on VS Code the images are not showing up

[kgryte]

Also, @Planeshifter and @headlessNode may have some thoughts.

[saurabhraghuvanshii]

It is good if sync with upstream with rebase also include because maximum contributer faces issue with rebase and in result they commit unwanted commits to file

[aayush0325]

It is good if sync with upstream with rebase also include because maximum contributer faces issue with rebase and in result they commit unwanted commits to file

Thanks for pointing it out @saurabhraghuvanshii! this one was on my todolist for this doc, writing it soon

[headlessNode]

Although this is not a FAQ. This suggestion, if accepted, could be implemented in a separate PR.

One thing I've noticed regarding questions asked on the Gitter channel is that people usually post a screenshot along with a vague question like "How do I solve this error?"

We could encourage a format which may include:

• Description (what they are trying to do, maybe a link to a PR)
• Issue encountered
• Steps taken (what they’ve tried so far)

Having a structured questions format could provide several benefits:

• People willing to help will quickly understand the issue resulting in little to no back-and-forth clarifications.
• When describing their issue in detail, people may come upon a solution on their own.

Would love to hear your thoughts on this @Planeshifter @kgryte

[kgryte]

@headlessNode Totally agree. Rarely do folks on Gitter provide enough info to help debug, resulting in a series of back and forths which is not a productive use of time.

[aayush0325]

adding this soon, thank you for your suggestion @headlessNode!

i plan to keep the format like this:

question: ---description of issue----
steps to reproduce: (if applicable)
error message: error message / images / logs / diverging results from expected values
current approach: --how the person has tried solving this---
reference: ---a PR link (if applicable)---

please feel free to suggest changes in this

[headlessNode]

@aayush0325 Great. We can iterate on this when you open a PR. 🎆

[aayush0325]

@aayush0325 Great. We can iterate on this when you open a PR. 🎆

I was planning to add it in this doc itself😅. would that be okay

[headlessNode]

IMO, it should be a separate document and we could link it in this doc like:

If you have a question that isn’t covered here, Feel free to reach out on our Gitter channel and make sure to follow our guide(Link) on how to ask questions.

@kgryte what do you think?

[kgryte]

It's a bit similar to our issue template: https://github.com/stdlib-js/stdlib/blob/develop/.github/ISSUE_TEMPLATE/bug_report.yml

Something for inspiration: https://stackoverflow.com/help/minimal-reproducible-example

I think we could probably add something similar for stdlib in the docs/ folder, and given that it might be a bit longer, I think it fine to place in a separate document. Whether that document is added in this PR or in a separate PR doesn't matter to me. Either is fine.

[aayush0325]

If you have a question that isn’t covered here, Feel free to reach out on our Gitter channel and make sure to follow our guide on how to ask questions.

makes sense to me, probably gonna raise another PR for that

[anandkaranubc]

@aayush0325 This is definitely a well-thought-out FAQ document!

Here’s my feedback:

1. We can add a list of questions (as links) at the top for better navigation, similar to this format.

2. A commonly asked question on the Gitter channel is: "I am a first-time contributor to stdlib, where should I start?" This question could be placed right after the introduction.

3. The section on setting up the development environment is focused only on the devcontainer setup, which might be misleading. It would be better to present two options:

   • Manually setting up the development environment
   • Setting up the devcontainer

   Also, the devcontainer does not support ARM64 architectures yet (this is on my to-do list). We can mention this issue for those interested in learning more or contributing to it.

4. The devcontainer setup section takes up a large portion of the document. A suggestion: We can move it to a separate document and link to it from the FAQ. In fact, this can be done for both manual and devcontainer setup instructions.

5. For the question on "Why do JS and C return different values?", we can add these references:

   • Discussion link
   • Reference comment

6. The weekly office hours meeting link can be updated to the issues section, where meeting details are posted.

7. For the question on "How do I generate test fixtures?", we can also mention:

   • make test-cov and make view-cov
   • This link for checking 100% test coverage locally.

8. The sample manifest.json content can be shortened to only include the "confs" section with a starting line like // Other sections above.... This would make it clearer for the reader on what's being pointed out.

9. In the Make commands section:

   • "Generate Julia Fixtures" → Rename to "Generate Test Fixtures" and list Python, Julia, and C++ as "some" examples, and add the below link for more.
     • Link: Test Fixtures.
   • "Run Examples" → Same as above. List make commands for running C and JS examples and add the below link.
     • Link: Examples.
   • "Run Benchmarks" → Same and add a link to Benchmarks.

10. We can add an "Other Links" section for useful resources:

    • Style guides (covers variable declaration, initialization, "negative" spacing, etc.)
    • "All" available make commands.

Other Popular Questions to Add (I understand that not all questions can be included due to length constraints and to keep the document readable):

1. "How should I name my PR?"

   • Short answer: Look at similar PRs that have already been merged.

2. "How do I call the stdlib bot on my PR?"

   • This can also include a note on "Understanding PR lint failures".

Phew! Open to everyone’s feedback and happy to provide draft answers for the above.

[kgryte]

Another thing to add: when to use decimals and when not to use decimals. E.g., https://github.com/stdlib-js/stdlib/pull/5353/files#r1966326512.

[kgryte]

A related document that we have can be found here: https://github.com/stdlib-js/stdlib/blob/develop/SUPPORT.md. This also touches on asking questions and seeking help.

[kgryte]

@aayush0325 Would you mind moving the docs into the docs/contributing folder? And also,

• dev_faqs.md => contributing/FAQ.md
• devcontainer_setup.md => contributing/setting_up_a_devcontainer.md

For images, such as screenshots, let's add them to a contributing/img folder.

[kgryte]

/stdlib merge

[kgryte]

I think this is good enough for now. We can go ahead and get this in and clean-up in follow-up commits/PRs.