Contributing to the TypeScript Toolkit

The TypeScript Toolkit Project welcomes all contributors! However, please note that all contributors are expected to follow all of the documented processes and procedures for contributing to the codebase.

• General Information
• Coding Style
• Adding a New Namespace
• Adding a New Tool
• Updating Existing Tools
• Contributing to the Project Configuration, Architecture, and Direction

General Information

• Unless you have been added as a contributor to the project repository, you will need to first create a fork of the repository before you can start making changes.

• When making Pull Requests, it is recommended to allow edits from maintainers to speed up the process of getting your changes merged into the upstream codebase.

Coding Style

In general, all contributions to the codebase should make as much of an attempt to match the existing coding style as possible.

Suggestions to alter the Project Coding Style should be made to the Discussions Forum on the Project GitHub. Changes to the codebase that only attempt to change the coding style or appearance will be rejected.

Warning

This section is incomplete:

Add or link to a comprehensive description of the Project Coding Style here.

Adding a New Namespace

To add a new Namespace used to group several related tools together to the TypeScript Toolkit:

1. Determine the name of the new namespace. Namespace names can only contain alpha-numeric characters and should always begin with a lowercase letter.

2. Checkout the Target Release Branch (e.g., releases/1.0.0).

   The Target Release Branch should always be a Minor Version increment of the Current Release Version where possible.

3. Create and checkout a new branch with the name feats/TARGET_RELEASE_BRANCH/NAMESPACE/namespace where:

   • TARGET_RELEASE_BRANCH is the Target Release Branch from Step 1
   • NAMESPACE is the name of the new namespace

4. Copy the New Namespace Template directory to the /toolkit directory and rename it to the name of the new namespace.

5. Update each of the files in the template, including:

   • index.ts
   • README.md

   Ensure that you replace all of instances of NAMESPACE with the name of the namespace and all instances of TARGET_VERSION with the Targeted Release Version identified in Step 2 (e.g., 1.0.0).

6. Update the Toolkit Index File (index.ts) and add the following line to the file:

   export * as NAMESPACE from "./NAMESPACE/index.js";

   replacing NAMESPACE with the name of the new namespace.

7. Update the exports section of package.json and add an entry for the new namespace:

   "exports": {
      ".": "./dist/index.js",
      "./NAMESPACE": "./dist/NAMESPACE/index.js"
   }

   replacing NAMESPACE with the name of the new namespace.

8. Commit and push all changes to the repository.

9. Open a Pull Request to merge the branch back into the Target Release Branch from Step 1 (e.g., releases/1.0.0).

10. Once approved and merged, update the API Documentation Wiki.

    1. Add a new page to the wiki for the new namespace.
    2. Update the Home Page and add a link to the new namespace page in the API Namespaces section.
    3. Update the Sidebar and add a link to the new namespace page.

Adding a New Tool

To add a new Namespace used to group several related tools together to the TypeScript Toolkit:

1. Determine the name of the new tool. Tool names can only contain alpha-numeric characters and should always begin with a lowercase letter.

2. Checkout the Target Release Branch (e.g., releases/1.0.0).

   The Target Release Branch should always be a Minor Version increment of the Current Release Version where possible.

3. Create and checkout a new branch with the name feats/TARGET_RELEASE_BRANCH/NAMESPACE/TOOL_NAME where:

   • TARGET_RELEASE_BRANCH is the Target Release Branch from Step 1
   • NAMESPACE is the name of the target namespace
   • TOOL_NAME is the name of the new tool.

4. Copy the New Tool Template directory to the Parent Namespace within the /toolkit directory and rename it to the name of the new tool.

5. Update each of the files in the template, including:

   • index.ts
   • README.md
   • module/index.ts
     • Add any additional TypeScript modules.
   • ts/index.ts
     • Add any additional TypeScript code snippet variants.
   • js/index.js
     • Add any additional JavaScript code snippet variants.

   Ensure that you replace all the instances of any of the following variables with the respective values:

   • NAMESPACE: The name of the namespace
   • TARGET_VERSION The Targeted Release Version identified in Step 2 (e.g., 1.0.0)
   • TOOL_NAME: The name of the new tool
   • AUTHOR_NAME: The name of the author(s) of the code.
   • AUTHOR_LINK: The link to the author(s) GitHub profile.
   • SOURCE_NAME: The name of the original source of the code (e.g., Stack Overflow).
   • SOURCE_URL: The link to the original source of the code.

6. Record all of the Inner-Package Dependencies and Dependents.

   1. Record all Dependencies and Dependents in the tool's README.md file.
   2. Update the README.md file of all Dependencies and Dependents accordingly.

7. Update the Parent Namespace Index File (/toolkit/NAMESPACE/index.ts) and add the following line to the file:

   export * from "./TOOL_NAME/index.js";

   replacing TOOL_NAME with the name of the new tool.

8. Update the Parent Namespace README.md and add a link to the tool directory:

   ## Tool List
   - [`TOOL_NAME`](TOOL_NAME): A short description for TOOL_NAME.
   

   Additionally, the examples can be updated to include code snippets from the new tool, if desired and appropriate.

9. Update the exports section of package.json and add an entry for the new tool beneath the entry for the Parent Namespace:

   "exports": {
      ".": "./dist/index.js",
      "./NAMESPACE": "./dist/NAMESPACE/index.js",
      "./NAMESPACE/TOOL_NAME": "./dist/NAMESPACE/TOOL_NAME/index.js"
   }

   replacing NAMESPACE with the name of the target namespace and TOOL_NAME with the name of the new tool.

10. Commit and push all changes to the repository.

11. Open a Pull Request to merge the branch back into the Target Release Branch from Step 1 (e.g., releases/1.0.0).

12. Once approved and merged, update the API Documentation Wiki.

    1. Update the page of the wiki containing the API Documentation for the Parent Namespace.
    2. Update the Sidebar and add a link to the new tool on the parent namespace page.

Updating Existing Tools

Warning

This section has not been written yet.

Contributing to the Project Configuration, Architecture, and Direction

Warning

This section has not been written yet.