From b59b1b729282b04e838fa955e1300c39d62d20fd Mon Sep 17 00:00:00 2001 From: Jongsun Suh <34228073+MajorLift@users.noreply.github.com> Date: Wed, 25 Oct 2023 16:35:58 -0700 Subject: [PATCH 1/2] Copilot-generated initial draft --- docs/idea-package-structure.md | 79 ++++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 docs/idea-package-structure.md diff --git a/docs/idea-package-structure.md b/docs/idea-package-structure.md new file mode 100644 index 00000000..d698d4bd --- /dev/null +++ b/docs/idea-package-structure.md @@ -0,0 +1,79 @@ +### Source and Build Files +- Source files should be placed in a directory named `src`. +- Build files should be placed in a directory named `dist`. +- It is important to ensure that the source files are organized in a logical and modular way, with each file containing a single module or class. +- The build files should be generated automatically using a build tool such as Webpack or Rollup, and should not be committed to the repository. + +### Tests and Test Helpers +- Tests should be placed in a directory named `test`. +- Test helpers should be placed in a directory named `test-helpers`. +- It is important to write comprehensive tests for all modules and classes, and to ensure that the tests are run automatically as part of the build process. +- Test helpers should be used to provide common functionality that is needed by multiple tests, such as setting up test data or mocking external dependencies. + +### Types +- Types should be included in the package by adding a `types` field to the `package.json` file. +- Types should be written using TypeScript or Flow, and should be kept up-to-date with the latest version of the package. +- It is important to ensure that the types are accurate and comprehensive, and that they cover all public APIs of the package. + +### Bash Scripts +- Bash scripts used for development tools or CI should be placed in a directory named `scripts`. +- It is important to ensure that the scripts are well-documented and easy to use, and that they are kept up-to-date with the latest version of the package. +- Bash scripts should be used sparingly, and only for tasks that cannot be easily accomplished using existing build tools or package scripts. + +### Contributor Documentation +- Contributor documentation should be placed in a directory named `contributing`. +- Contributor documentation should include information on how to contribute to the package, including guidelines for submitting pull requests and reporting issues. +- It is important to ensure that the contributor documentation is up-to-date and accurate, and that it is easy to understand for first-time contributors. + +### README +- The README should include a brief description of the package, installation instructions, usage instructions, and a list of contributors. +- It is important to ensure that the README is well-written and easy to understand, and that it provides all the information that a user would need to get started with the package. +- The README should be kept up-to-date with the latest version of the package, and should be reviewed periodically to ensure that it is still accurate and relevant. + +### Package.json Fields/Metadata +- The `package.json` file should include the following fields: + - `name`: The name of the package. + - `version`: The version of the package. + - `description`: A brief description of the package. + - `main`: The entry point for the package. + - `scripts`: A list of scripts that can be run with `npm run`. + - `repository`: The URL of the repository. + - `keywords`: A list of keywords that describe the package. + - `author`: The name and email address of the package author. + - `license`: The license under which the package is released. + - `bugs`: The URL where issues can be reported. + - `homepage`: The URL of the package's homepage. +- It is important to ensure that all fields are accurate and up-to-date, and that they provide all the information that a user would need to understand and use the package. +- The `name` field should be unique and descriptive, and should follow the naming conventions for npm packages. +- The `version` field should follow the semantic versioning conventions. +- The `description` field should provide a brief overview of the package's functionality. +- The `main` field should point to the entry point for the package. +- The `scripts` field should include all the scripts that are needed to build, test, and run the package. +- The `repository` field should point to the URL of the repository. +- The `keywords` field should include a list of keywords that describe the package. +- The `author` field should include the name and email address of the package author. +- The `license` field should specify the license under which the package is released. +- The `bugs` field should point to the URL where issues can be reported. +- The `homepage` field should point to the URL of the package's homepage. + +### License +- The license should be placed in a file named `LICENSE`. +- It is recommended to use a standard open-source license, such as the MIT License or Apache License. +- Before releasing a package, it is important to get approval from the legal team to ensure that the license is appropriate for the project. +- It is important to ensure that the license is included in all distributions of the package, and that it is clearly visible and easy to understand. + +### Generated API Documentation +- Generated API documentation should be placed in a directory named `docs`. +- The documentation should be hosted on `metamask.github.io//`. +- It is important to ensure that the API documentation is accurate and up-to-date, and that it covers all public APIs of the package. +- The documentation should be generated automatically using a tool such as JSDoc or TypeDoc, and should be reviewed periodically to ensure that it is still accurate and relevant. + +### Configuration Files +- Configuration files should be placed in a directory named `config`. +- Configuration files should be used to store configuration data that is needed by the package, such as API keys or database credentials. +- It is important to ensure that the configuration files are well-documented and easy to use, and that they are kept up-to-date with the latest version of the package. + +### Keeping Packages in Sync with the Module Template +- To keep packages in sync with the module template, use the `@metamask/template-sync` tool. +- It is important to ensure that the package is kept up-to-date with the latest version of the module template, and that any changes to the template are incorporated into the package as soon as possible. +- It is also important to ensure that any customizations to the package are not overwritten by updates to the module template, and that any conflicts are resolved in a timely manner. \ No newline at end of file From 159537fe3ff7dedc45a7b9de2e8d8b73beee51ea Mon Sep 17 00:00:00 2001 From: Jongsun Suh <34228073+MajorLift@users.noreply.github.com> Date: Wed, 25 Oct 2023 16:56:10 -0700 Subject: [PATCH 2/2] Linter fixes --- docs/idea-package-structure.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/idea-package-structure.md b/docs/idea-package-structure.md index d698d4bd..616541c9 100644 --- a/docs/idea-package-structure.md +++ b/docs/idea-package-structure.md @@ -1,36 +1,47 @@ +# Ideal Package Structure + +## Outline + ### Source and Build Files + - Source files should be placed in a directory named `src`. - Build files should be placed in a directory named `dist`. - It is important to ensure that the source files are organized in a logical and modular way, with each file containing a single module or class. - The build files should be generated automatically using a build tool such as Webpack or Rollup, and should not be committed to the repository. ### Tests and Test Helpers + - Tests should be placed in a directory named `test`. - Test helpers should be placed in a directory named `test-helpers`. - It is important to write comprehensive tests for all modules and classes, and to ensure that the tests are run automatically as part of the build process. - Test helpers should be used to provide common functionality that is needed by multiple tests, such as setting up test data or mocking external dependencies. ### Types + - Types should be included in the package by adding a `types` field to the `package.json` file. - Types should be written using TypeScript or Flow, and should be kept up-to-date with the latest version of the package. - It is important to ensure that the types are accurate and comprehensive, and that they cover all public APIs of the package. ### Bash Scripts + - Bash scripts used for development tools or CI should be placed in a directory named `scripts`. - It is important to ensure that the scripts are well-documented and easy to use, and that they are kept up-to-date with the latest version of the package. - Bash scripts should be used sparingly, and only for tasks that cannot be easily accomplished using existing build tools or package scripts. ### Contributor Documentation + - Contributor documentation should be placed in a directory named `contributing`. - Contributor documentation should include information on how to contribute to the package, including guidelines for submitting pull requests and reporting issues. - It is important to ensure that the contributor documentation is up-to-date and accurate, and that it is easy to understand for first-time contributors. ### README + - The README should include a brief description of the package, installation instructions, usage instructions, and a list of contributors. - It is important to ensure that the README is well-written and easy to understand, and that it provides all the information that a user would need to get started with the package. - The README should be kept up-to-date with the latest version of the package, and should be reviewed periodically to ensure that it is still accurate and relevant. ### Package.json Fields/Metadata + - The `package.json` file should include the following fields: - `name`: The name of the package. - `version`: The version of the package. @@ -57,23 +68,27 @@ - The `homepage` field should point to the URL of the package's homepage. ### License + - The license should be placed in a file named `LICENSE`. - It is recommended to use a standard open-source license, such as the MIT License or Apache License. - Before releasing a package, it is important to get approval from the legal team to ensure that the license is appropriate for the project. - It is important to ensure that the license is included in all distributions of the package, and that it is clearly visible and easy to understand. ### Generated API Documentation + - Generated API documentation should be placed in a directory named `docs`. - The documentation should be hosted on `metamask.github.io//`. - It is important to ensure that the API documentation is accurate and up-to-date, and that it covers all public APIs of the package. - The documentation should be generated automatically using a tool such as JSDoc or TypeDoc, and should be reviewed periodically to ensure that it is still accurate and relevant. ### Configuration Files + - Configuration files should be placed in a directory named `config`. - Configuration files should be used to store configuration data that is needed by the package, such as API keys or database credentials. - It is important to ensure that the configuration files are well-documented and easy to use, and that they are kept up-to-date with the latest version of the package. ### Keeping Packages in Sync with the Module Template + - To keep packages in sync with the module template, use the `@metamask/template-sync` tool. - It is important to ensure that the package is kept up-to-date with the latest version of the module template, and that any changes to the template are incorporated into the package as soon as possible. -- It is also important to ensure that any customizations to the package are not overwritten by updates to the module template, and that any conflicts are resolved in a timely manner. \ No newline at end of file +- It is also important to ensure that any customizations to the package are not overwritten by updates to the module template, and that any conflicts are resolved in a timely manner.