manual icon indicating copy to clipboard operation
manual copied to clipboard

Improve contributing guidelines

Open etodanik opened this issue 2 years ago • 4 comments

I suggest the maintainers add a CONTRIBUTING.md file: https://mozillascience.github.io/working-open-workshop/contributing/

As someone who just had the need to clone Deno & poke around, I can say that beyond just regular rust setup, there are a lot of not fully clear things, e.g:

  • What does a comfortable DX looks like for debugging *.js files from ext/?
  • Known issues with compilation? (for example, it seemed like cargo was over-zealously rebuilding some packages for me

And just in general, it's a very friendly way to let someone who can contribute code or debug something know how to get the rubber to hit the road with minimal headaches.

If those instructions do exist somewhere, you could link them from CONTRIBUTING.md or vice versa, because if they DO exist, they weren't very easily discoverable (I sure did try)

etodanik avatar Aug 26 '22 17:08 etodanik

There is a contributing section in the manual https://deno.land/[email protected]/contributing (linked in the README: https://github.com/denoland/deno#contributing)

littledivy avatar Aug 26 '22 17:08 littledivy

Oh wow. Ok, my bad! My instinct for not looking at headers or footers must have blinded me.

etodanik avatar Aug 26 '22 17:08 etodanik

@littledivy for what its worth, the schematic diagram is broken: https://deno.land/[email protected]/contributing/architecture

And after reading through that section, I still reinstate my comment that the guide leaves a few things unclear that might be clear to the core team or seasoned contributors. Namely, best practices and workflows for debugging *.js code in ext/. How does maintainer DX look like for those? Surely they don't simply put in console.log everywhere? Is there a way to plug V8 debugging correctly, work with breakpoints, debugger e.t.c?

A little even the tiniest guide on that would go a long way.

I think everyone would win from a little bit of extra hand-holding just to get "into the mind" of a Deno DX workflow.

etodanik avatar Aug 26 '22 17:08 etodanik

The diagram is covered by denoland/manual#235.

kitsonk avatar Aug 27 '22 01:08 kitsonk