From f05c8a1ca2844b82e59a7511153935f8e2d5cb21 Mon Sep 17 00:00:00 2001 From: Kwanghyun On Date: Fri, 25 Oct 2024 13:01:44 +0900 Subject: [PATCH 1/6] Add documents for contributors --- CONTRIBUTING.md | 101 +++++++++++++++++++++++++++++++++++++++++++++ DEVELOPMENT.md | 45 ++++++++++++++++++++ esbuild.config.mjs | 3 +- 3 files changed, 147 insertions(+), 2 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 DEVELOPMENT.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..04d89ab --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,101 @@ +# Contributing to Obsidian Smart Composer + +We welcome contributions to Obsidian Smart Composer! This document will guide you through the process of contributing to the project. + +## Development Workflow + +1. Clone the repository to your Obsidian vault's plugins directory: + ``` + git clone https://github.com/glowingjade/obsidian-smart-composer.git /path/to/your/vault/.obsidian/plugins/obsidian-smart-composer + ``` +2. Navigate to the plugin directory: + ``` + cd /path/to/your/vault/.obsidian/plugins/obsidian-smart-composer + ``` +3. Run the following commands to install dependencies and start the development server: + ``` + npm install + npm run dev + ``` +4. Start making changes to the plugin code. To test your changes: + - Reload Obsidian manually, or + - Use the [Hot Reload plugin](https://github.com/pjeby/hot-reload) for automatic reloading during development +5. To check if everything is building correctly, set the `logLevel` to 'debug' in `esbuild.config.mjs`: + ```javascript + logLevel: 'debug', + ``` + This will provide more detailed output during the build process, helping you identify any issues. + +## Database Development + +We use PGlite and Drizzle ORM for database management in this project. This section will guide you through working with the database schema and making changes. + +### Libraries + +1. **PGlite**: A lightweight PostgreSQL implementation that runs in various JavaScript environments, allowing use of PostgreSQL syntax without a full database server. [Learn more](https://pglite.dev/docs/) + +2. **Drizzle ORM**: A TypeScript ORM providing type-safe database interactions with a SQL-like query API, supporting multiple database dialects. [Learn more](https://orm.drizzle.team/docs/overview) + +### Updating the Database Schema + +To update the database schema: + +1. Modify the existing schema as needed in the `src/db/schema.ts` file. +2. After making changes, run the following command to generate migration files: + ``` + npm run migrate:generate + ``` +3. Review the generated migration files in the `drizzle` directory. +4. Compile the migration files into a single JSON file by running: + ``` + npm run migrate:compile + ``` + This will create or update the `src/db/migrations.json` file. Note that migration files in the 'drizzle' directory won't affect the project until they are compiled into this JSON file, which is used in the actual migration process. + +### Handling Migration Files + +We recommend creating a single migration file for each change. To squash multiple changes into a single migration file after finalizing your schema.ts: + +1. Delete the newly created migration files in the `drizzle` directory. +2. Delete the new snapshot.json files in the `drizzle/meta` directory. +3. Remove new entries in `drizzle/meta/_journal.json`. +4. Run the migration generation command again to create a final, consolidated migration file: + ``` + npm run migrate:generate + ``` + +This process ensures a clean and organized migration history. + +## Sending a Pull Request + +The core team is monitoring for pull requests. We will review your pull request and either merge it, request changes to it, or close it with an explanation. + +**Before submitting a pull request**, please make sure the following is done: + +1. Fork the repository and create your branch from `main`. +2. Run `npm install` in the repository root. +3. If you've fixed a bug or added code that should be tested, add tests! +4. Ensure the test suite passes (`npm test`). +5. Check for type errors (`npm run type:check`). +6. Check for linting errors (`npm run lint:check`). +7. You can fix linting errors automatically with `npm run lint:fix`. + +## Development Issues and Solutions + +For common development issues, their solutions, and other helpful information for contributors, please refer to the following resources: + +1. [DEVELOPMENT.md](./DEVELOPMENT.md): Contains detailed information about the development process, common issues, and their solutions. +2. [Issue Tracker](https://github.com/glowingjade/obsidian-smart-composer/issues): Check our issue tracker for detailed problem descriptions and solutions. +3. [GitHub Discussions](https://github.com/glowingjade/obsidian-smart-composer/discussions): Join our community discussions for interactive problem-solving and knowledge sharing. + +We encourage contributors to review these resources before starting development and to help keep them updated with new findings. + +### Known Issue: Memory Leak During Plugin Reloading + +A memory leak has been identified when reloading the plugin. This may not be critical for end-users who typically don't reload the plugin frequently, but it can become problematic for developers who reload often during the development process. If you experience Obsidian becoming unresponsive or slow after reloading the plugin multiple times, it may be due to this memory leak. We are actively investigating the root cause and working on potential fixes. Any reports or fixes in this area are appreciated. + +## License + +This project is licensed under the GPT-3.0 License. By contributing to this project, you agree that your contributions will be licensed under the GPT-3.0 License. Please make sure you understand and comply with the terms of this license before submitting any contributions. + +For more information about the GPT-3.0 License, please refer to the LICENSE file in the root of this repository or visit the official GPT-3.0 License website. diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 0000000..a84923a --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,45 @@ +# Development Notes + +## PGlite in Obsidian Environment + +PGlite typically uses the `node:fs` module to load bundle files. However, Obsidian plugins run in a browser-like environment where `node:fs` is not available. This presents a challenge in implementing PGlite in Obsidian's environment. + +To address this, we developed a workaround in `src/utils/vector-db/repository.ts`: + +1. Manually fetch required PGlite resources (Postgres data, WebAssembly module, and Vector extension). +2. Use PGlite's option to directly set bundle files or URLs when initializing the database. + +This approach allows PGlite to function in Obsidian's browser-like environment without relying on `node:fs`. + +In `esbuild.config.mjs`, we set the `process` variable to an empty object to prevent PGlite from detecting a Node environment: + +```javascript:esbuild.config.mjs +define: { + // ... other definitions ... + process: '{}', + // ... other definitions ... +}, +``` + +While this solution works currently, we should be aware that setting `process` to an empty object might cause issues with other libraries that rely on this variable. We'll monitor for any potential problems and explore alternative solutions if needed. + +## ESM Compatibility Shim for PGlite + +Our project faces a challenge because we use the PGlite module, which is written in ECMAScript modules (ESM) and doesn't support CommonJS directly. However, our Obsidian plugin is built using CommonJS for broader compatibility. This mismatch creates issues, particularly with ESM-specific features like `import.meta.url` that PGlite relies on. + +To address this, we've implemented a shim in `import-meta-url-shim.js`. This shim provides a workaround for the `import.meta.url` feature, allowing it to function in our CommonJS environment. We inject this shim and define `import.meta.url` in our `esbuild.config.mjs`: + +```javascript:esbuild.config.mjs +define: { + // ... other definitions ... + 'import.meta.url': 'import_meta_url', + // ... other definitions ... +}, +inject: [path.resolve('import-meta-url-shim.js')], +``` + +By implementing this shim, we can use PGlite (an ESM module) within our CommonJS-based Obsidian plugin. It ensures that ESM-specific features like `import.meta.url` work correctly, bridging the gap between ESM and CommonJS environments. + +## Memory Leak During Plugin Reloading + +A memory leak has been identified when reloading the plugin. This may not be critical for end-users who typically don't reload the plugin frequently, but it can become problematic for developers who reload often during the development process. If you experience Obsidian becoming unresponsive or slow after reloading the plugin multiple times, it may be due to this memory leak. We are actively investigating the root cause and working on potential fixes. Any reports or fixes in this area are appreciated. \ No newline at end of file diff --git a/esbuild.config.mjs b/esbuild.config.mjs index 8f61b23..0e8e42f 100644 --- a/esbuild.config.mjs +++ b/esbuild.config.mjs @@ -41,12 +41,11 @@ const context = await esbuild.context({ }, inject: [path.resolve('import-meta-url-shim.js')], target: 'es2020', - logLevel: 'info', + logLevel: 'info', // 'debug' for more detailed output sourcemap: prod ? false : 'inline', treeShaking: true, outfile: 'main.js', minify: prod, - // logLevel: 'debug', }) if (prod) { From ff7b75286152ac94b8d66b54ef39e7d272ccf801 Mon Sep 17 00:00:00 2001 From: Kwanghyun On Date: Fri, 25 Oct 2024 13:04:55 +0900 Subject: [PATCH 2/6] Add new lines --- CONTRIBUTING.md | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 04d89ab..22f38bf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,26 +5,29 @@ We welcome contributions to Obsidian Smart Composer! This document will guide yo ## Development Workflow 1. Clone the repository to your Obsidian vault's plugins directory: + ``` git clone https://github.com/glowingjade/obsidian-smart-composer.git /path/to/your/vault/.obsidian/plugins/obsidian-smart-composer ``` + 2. Navigate to the plugin directory: + ``` cd /path/to/your/vault/.obsidian/plugins/obsidian-smart-composer ``` + 3. Run the following commands to install dependencies and start the development server: + ``` npm install npm run dev ``` + 4. Start making changes to the plugin code. To test your changes: - Reload Obsidian manually, or - Use the [Hot Reload plugin](https://github.com/pjeby/hot-reload) for automatic reloading during development -5. To check if everything is building correctly, set the `logLevel` to 'debug' in `esbuild.config.mjs`: - ```javascript - logLevel: 'debug', - ``` - This will provide more detailed output during the build process, helping you identify any issues. + +5. To check if everything is building correctly, set the `logLevel: debug` in `esbuild.config.mjs`. This will provide more detailed output during the build process, helping you identify any issues. ## Database Development @@ -42,14 +45,18 @@ To update the database schema: 1. Modify the existing schema as needed in the `src/db/schema.ts` file. 2. After making changes, run the following command to generate migration files: + ``` npm run migrate:generate ``` + 3. Review the generated migration files in the `drizzle` directory. 4. Compile the migration files into a single JSON file by running: + ``` npm run migrate:compile ``` + This will create or update the `src/db/migrations.json` file. Note that migration files in the 'drizzle' directory won't affect the project until they are compiled into this JSON file, which is used in the actual migration process. ### Handling Migration Files @@ -60,6 +67,7 @@ We recommend creating a single migration file for each change. To squash multipl 2. Delete the new snapshot.json files in the `drizzle/meta` directory. 3. Remove new entries in `drizzle/meta/_journal.json`. 4. Run the migration generation command again to create a final, consolidated migration file: + ``` npm run migrate:generate ``` From 78fd5e3033f74dccb2d0973a0b7c41a97702200c Mon Sep 17 00:00:00 2001 From: Kwanghyun On Date: Fri, 25 Oct 2024 13:17:55 +0900 Subject: [PATCH 3/6] Update README.md --- CONTRIBUTING.md | 4 +--- README.md | 30 ++++++++++++++++++++++++++++-- 2 files changed, 29 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 22f38bf..3f270d7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -104,6 +104,4 @@ A memory leak has been identified when reloading the plugin. This may not be cri ## License -This project is licensed under the GPT-3.0 License. By contributing to this project, you agree that your contributions will be licensed under the GPT-3.0 License. Please make sure you understand and comply with the terms of this license before submitting any contributions. - -For more information about the GPT-3.0 License, please refer to the LICENSE file in the root of this repository or visit the official GPT-3.0 License website. +This project is licensed under the [GPT-3.0 License](LICENSE). By contributing to this project, you agree that your contributions will be licensed under the GPT-3.0 License. Please make sure you understand and comply with the terms of this license before submitting any contributions. \ No newline at end of file diff --git a/README.md b/README.md index 7f50ce9..c8ccd16 100644 --- a/README.md +++ b/README.md @@ -95,6 +95,32 @@ Obsidian Smart Composer adds a few commands to work with AI. You can set custom - Copilot-like autocomplete - Context-aware suggestions based on your writing style and vault content -## Contribution +## Feedback and Support -All kinds of contributions are welcome, including bug reports, bug fixes, improvements to documentation, and general enhancements. If you have an idea for a major feature, please create an issue to discuss its feasibility and the best implementation approach. +We value your input and want to ensure you can easily share your thoughts and report any issues: + +- **Bug Reports**: If you encounter any bugs or unexpected behavior, please submit an issue on our [GitHub Issues](https://github.com/glowingjade/obsidian-smart-composer/issues) page. Be sure to include as much detail as possible to help us reproduce and address the problem. + +- **Feature Requests**: For new feature ideas or enhancements, please use our [GitHub Discussions - Ideas](https://github.com/glowingjade/obsidian-smart-composer/discussions/categories/ideas) page. Create a new discussion to share your suggestions. This allows for community engagement and helps us prioritize future developments. + +- **Show and Tell**: We love seeing how you use Obsidian Smart Composer! Share your unique use cases, workflows, or interesting applications of the plugin in the [GitHub Discussions - Show and Tell](https://github.com/glowingjade/obsidian-smart-composer/discussions/categories/show-and-tell) page. + +Your feedback and experiences are crucial in making Obsidian Smart Composer better for everyone! + +## Contributing + +We welcome all kinds of contributions to Obsidian Smart Composer, including bug reports, bug fixes, documentation improvements, and feature enhancements. + +If you're interested in contributing, please refer to our [CONTRIBUTING.md](CONTRIBUTING.md) file for detailed information on: + +- Setting up the development environment +- Our development workflow +- Working with the database schema +- The process for submitting pull requests +- Known issues and solutions for developers + +For major feature ideas, please create an issue first to discuss feasibility and implementation approach. + +## License + +This project is licensed under the [GPT-3.0 License](LICENSE). \ No newline at end of file From 3e364f6697bac2e1ff343a6f604490f8b4b83b9c Mon Sep 17 00:00:00 2001 From: Kwanghyun On Date: Fri, 25 Oct 2024 13:20:11 +0900 Subject: [PATCH 4/6] Update license --- CONTRIBUTING.md | 2 +- README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3f270d7..a9c328d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -104,4 +104,4 @@ A memory leak has been identified when reloading the plugin. This may not be cri ## License -This project is licensed under the [GPT-3.0 License](LICENSE). By contributing to this project, you agree that your contributions will be licensed under the GPT-3.0 License. Please make sure you understand and comply with the terms of this license before submitting any contributions. \ No newline at end of file +This project is licensed under the [MIT License](LICENSE). By contributing to this project, you agree that your contributions will be licensed under the MIT License. Please make sure you understand and comply with the terms of this license before submitting any contributions. diff --git a/README.md b/README.md index c8ccd16..5e79be6 100644 --- a/README.md +++ b/README.md @@ -123,4 +123,4 @@ For major feature ideas, please create an issue first to discuss feasibility and ## License -This project is licensed under the [GPT-3.0 License](LICENSE). \ No newline at end of file +This project is licensed under the [MIT License](LICENSE). \ No newline at end of file From b6350b8fb342be15cf071df3b9aebd4aeb8aebfa Mon Sep 17 00:00:00 2001 From: Kwanghyun On Date: Fri, 25 Oct 2024 13:22:02 +0900 Subject: [PATCH 5/6] Fix lint --- CONTRIBUTING.md | 1 + DEVELOPMENT.md | 2 +- README.md | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a9c328d..ae292a9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,6 +24,7 @@ We welcome contributions to Obsidian Smart Composer! This document will guide yo ``` 4. Start making changes to the plugin code. To test your changes: + - Reload Obsidian manually, or - Use the [Hot Reload plugin](https://github.com/pjeby/hot-reload) for automatic reloading during development diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index a84923a..fc51395 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -42,4 +42,4 @@ By implementing this shim, we can use PGlite (an ESM module) within our CommonJS ## Memory Leak During Plugin Reloading -A memory leak has been identified when reloading the plugin. This may not be critical for end-users who typically don't reload the plugin frequently, but it can become problematic for developers who reload often during the development process. If you experience Obsidian becoming unresponsive or slow after reloading the plugin multiple times, it may be due to this memory leak. We are actively investigating the root cause and working on potential fixes. Any reports or fixes in this area are appreciated. \ No newline at end of file +A memory leak has been identified when reloading the plugin. This may not be critical for end-users who typically don't reload the plugin frequently, but it can become problematic for developers who reload often during the development process. If you experience Obsidian becoming unresponsive or slow after reloading the plugin multiple times, it may be due to this memory leak. We are actively investigating the root cause and working on potential fixes. Any reports or fixes in this area are appreciated. diff --git a/README.md b/README.md index 5e79be6..dc5c259 100644 --- a/README.md +++ b/README.md @@ -123,4 +123,4 @@ For major feature ideas, please create an issue first to discuss feasibility and ## License -This project is licensed under the [MIT License](LICENSE). \ No newline at end of file +This project is licensed under the [MIT License](LICENSE). From fd54131587aad3f4e8ef455a137b03c48b812505 Mon Sep 17 00:00:00 2001 From: Kwanghyun On Date: Fri, 25 Oct 2024 13:33:47 +0900 Subject: [PATCH 6/6] Update github discussions category name --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index dc5c259..ff36d2d 100644 --- a/README.md +++ b/README.md @@ -101,9 +101,9 @@ We value your input and want to ensure you can easily share your thoughts and re - **Bug Reports**: If you encounter any bugs or unexpected behavior, please submit an issue on our [GitHub Issues](https://github.com/glowingjade/obsidian-smart-composer/issues) page. Be sure to include as much detail as possible to help us reproduce and address the problem. -- **Feature Requests**: For new feature ideas or enhancements, please use our [GitHub Discussions - Ideas](https://github.com/glowingjade/obsidian-smart-composer/discussions/categories/ideas) page. Create a new discussion to share your suggestions. This allows for community engagement and helps us prioritize future developments. +- **Feature Requests**: For new feature ideas or enhancements, please use our [GitHub Discussions - Ideas & Feature Requests](https://github.com/glowingjade/obsidian-smart-composer/discussions/categories/ideas-feature-requests) page. Create a new discussion to share your suggestions. This allows for community engagement and helps us prioritize future developments. -- **Show and Tell**: We love seeing how you use Obsidian Smart Composer! Share your unique use cases, workflows, or interesting applications of the plugin in the [GitHub Discussions - Show and Tell](https://github.com/glowingjade/obsidian-smart-composer/discussions/categories/show-and-tell) page. +- **Show and Tell**: We love seeing how you use Obsidian Smart Composer! Share your unique use cases, workflows, or interesting applications of the plugin in the [GitHub Discussions - Smart Composer Showcase](https://github.com/glowingjade/obsidian-smart-composer/discussions/categories/smart-composer-showcase) page. Your feedback and experiences are crucial in making Obsidian Smart Composer better for everyone!