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

Put together a more thorough CONTRIBUTING guide #2598

Open
LukeAbby opened this issue Jul 7, 2024 · 3 comments
Open

Put together a more thorough CONTRIBUTING guide #2598

LukeAbby opened this issue Jul 7, 2024 · 3 comments
Assignees
Labels
documentation Improvements or additions to documentation

Comments

@LukeAbby
Copy link
Collaborator

LukeAbby commented Jul 7, 2024

This effectively boils down to the many pitfalls of TypeScript. Common issues seems to be:

  • Determining the right type for a plain object. Usually Record<string, unknown>.
  • Using InexactPartial appropriately.
  • Not writing foo?: T | undefined in function signatures; only for object properties does the distinction between foo?: T and foo?: T | undefined matter.
  • Writing effective tests.
  • The process of diffing versions.
  • Getting started with the helper types.
  • etc.

Ideally if lints could be find for these it'd ease the burden into becoming more automated.

@JPMeehan
Copy link
Collaborator

JPMeehan commented Jul 7, 2024

Part of #2528

@JPMeehan
Copy link
Collaborator

JPMeehan commented Jul 7, 2024

Some more

  • What to do when the core type documentation is wrong
  • Deprecation handling
  • Explanation of fields.mjs
  • Policy for protected vs internal vs private

@JPMeehan JPMeehan added the documentation Improvements or additions to documentation label Jul 7, 2024
@LukeAbby
Copy link
Collaborator Author

LukeAbby commented Jul 10, 2024

  • Setting up VSCode with ESLint/TypeScript/other recommended extensions.
  • Why we do export {} in every new file that doesn't have an import/export. (To make sure the files aren't automatically ambient)
  • Running tests.
  • How to run tsc to generate type definitions from Foundry source. This is technically a part of diffing versions but I listed it here to make sure I won't forget.
  • A quick guide on namespaces. They're a pretty unusual thing in TypeScript these days which I actually think is a bit of a shame.
  • How to find a good first issue.
  • Explanation of the advanced patterns in the repo for things like Mixins
  • Possibly a brief explanation of the helper types.
  • What Foundry documentation to copy over. For example you probably shouldn't copy over /* ************** */ comments.
  • What documentation to add. For example if something is only initialized during a certain hook.
  • Common Foundry TSDoc mappings e.g. Object<T> -> Record<string, T> or so on.
  • When to use MaybePromise.
  • How to provide the defaults of something, e.g. a function parameter.

@kmoschcau kmoschcau self-assigned this Jul 10, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

3 participants