Skip to content

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

Merged
ezolenko merged 1 commit into
ezolenko:masterfrom
agilgur5:docs-add-learning-the-codebase
Jun 7, 2022
Merged

docs: add a section on "Learning the codebase" to CONTRIBUTING.md#351
ezolenko merged 1 commit into
ezolenko:masterfrom
agilgur5:docs-add-learning-the-codebase

Conversation

@agilgur5

@agilgur5 agilgur5 commented Jun 7, 2022

Copy link
Copy Markdown
Collaborator

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

ezolenko commented Jun 7, 2022

Copy link
Copy Markdown
Owner

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