Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add a section on "Learning the codebase" to CONTRIBUTING.md #351

Merged
merged 1 commit into from
Jun 7, 2022

Conversation

agilgur5
Copy link
Collaborator

@agilgur5 agilgur5 commented Jun 7, 2022

Summary

Add a sizeable "Learning the codebase" section to the contributing docs to help new contributors!

Details

  • thought that as it's somewhat? fresh in my head (pending if you consider years of sporadic contributions), it would be really good to document for new contributors who don't know where to start

  • other than being good practice, thought this could be useful for a number of reasons:

    1. helpful resources like the TSConfig Reference, the TS Compiler Wiki, and the Rollup Plugin docs, that I read through with some frequency
      • (and I contribute lots to the TSConfig Reference too, it's by far the most useful resource in the ecosystem, IMO)
    2. explaining directly in the docs how sparsely documented the TS Compiler API is
      • like it really makes things difficult and every time I'm looking to contribute a bigger bugfix I look at the TS Wiki and don't get a super helpful answer there
    3. this codebase is actually fairly simple (it's the main reason I became a contributor! as I've stated in a few issues) and truly not that hard to get started with
      • but there are some rabbit holes you can go down that can scare away some contributors, like the cache code or the logging nuances
        • so this gives a bit of a guide to not fall into some rabbit holes and start off with the less complex bits of code
    4. encourage more contributors to make some PRs like I first did!

Review Notes

Feel free to add your own recommendations here! And let me know what you think of my take and the resources I use; I'm assuming we use similar docs/references, but who knows

- thought that as it's somewhat? fresh in my head (pending if you
  consider years of sporadic contributions), it would be really good to
  document for new contributors who don't know where to start

- other than being good practice, thought this could be useful for a
  number of reasons:
  1. helpful resources like the TSConfig Reference, the TS Wiki, and the
     Rollup Plugin docs, that I read through with some frequency
     - (and contribute lots to the TSConfig Reference too, it's by far
      the most useful resource in the ecosystem, IMO)
  2. explaining directly in the docs how sparsely documented the TS
     Compiler API is
     - like it really makes things difficult and every time I'm looking
       to contribute a bigger bugfix I look at the TS Wiki and don't
       get a super helpful answer there
  3. this codebase is actually fairly simple (it's the main reason I
    became a contributor, as I've stated in a few issues) and truly not
    that hard to get started with
    - but there are some rabbit holes you can go down that can scare
      away some contributors, like the cache code or the logging nuances
      - so this gives a bit of a guide to not fall into some rabbit
        holes and start off with the less complex bits of code
  4. encourage more contributors to make some PRs like I first did!
@agilgur5 agilgur5 added scope: docs Documentation could be improved. Or changes that only affect docs kind: internal Changes only affect the internals, and _not_ the public API or external-facing docs labels Jun 7, 2022
@ezolenko
Copy link
Owner

ezolenko commented Jun 7, 2022

Heh, Language Service API documentation does leave a lot to be desired...

@ezolenko ezolenko merged commit 03cfb04 into ezolenko:master Jun 7, 2022
@agilgur5 agilgur5 added the topic: TS Compiler API Docs Related to the severely lacking TS Compiler API Docs label Jun 28, 2022
@agilgur5 agilgur5 deleted the docs-add-learning-the-codebase branch July 2, 2023 21:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
kind: internal Changes only affect the internals, and _not_ the public API or external-facing docs scope: docs Documentation could be improved. Or changes that only affect docs topic: TS Compiler API Docs Related to the severely lacking TS Compiler API Docs
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants