From 283aa27152a53ba4cc278e5b8a2f75cbeab8c729 Mon Sep 17 00:00:00 2001
From: Soufiane Fariss <rev.fariss@gmail.com>
Date: Mon, 5 Aug 2024 15:47:03 +0200
Subject: [PATCH] add DEVELOPMENT.md

---
 .github/workflows/deploy-webui.yml |  12 +--
 web/explorer/DEVELOPMENT.md        | 115 +++++++++++++++++++++++++++++
 web/explorer/README.md             |   2 +-
 3 files changed, 122 insertions(+), 7 deletions(-)
 create mode 100644 web/explorer/DEVELOPMENT.md

diff --git a/.github/workflows/deploy-webui.yml b/.github/workflows/deploy-webui.yml
index de08df6e..2487633d 100644
--- a/.github/workflows/deploy-webui.yml
+++ b/.github/workflows/deploy-webui.yml
@@ -37,25 +37,25 @@ jobs:
         with:
           node-version: 20
           cache: 'npm'
-          cache-dependency-path: './webui/package-lock.json'
+          cache-dependency-path: './web/explorer/package-lock.json'
       - name: Install dependencies
         run: npm ci
-        working-directory: ./webui
+        working-directory: ./web/explorer
       - name: Lint
         run: npm run lint
-        working-directory: ./webui
+        working-directory: ./web/explorer
       - name: Run unit tests
         run: npm run test
-        working-directory: ./webui
+        working-directory: ./web/explorer
       - name: Build
         run: npm run build
-        working-directory: ./webui
+        working-directory: ./web/explorer
       - name: Setup Pages
         uses: actions/configure-pages@v4
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: './webui/dist'
+          path: './web/explorer/dist'
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4
diff --git a/web/explorer/DEVELOPMENT.md b/web/explorer/DEVELOPMENT.md
new file mode 100644
index 00000000..2ceececf
--- /dev/null
+++ b/web/explorer/DEVELOPMENT.md
@@ -0,0 +1,115 @@
+# Development Guide for capa-webui
+
+This guide will help you set up the Capa Explorer WebUI project for local development.
+
+## Prerequisites
+
+Before you begin, ensure you have the following installed:
+- Node.js (v20.x or later recommended)
+- npm (v10.x or later)
+- Git
+
+## Setting Up the Development Environment
+
+1. Clone the repository:
+   ```
+   git clone https://github.com/mandiat/capa.git
+   cd capa/web/explorer
+   ```
+
+2. Install dependencies:
+   ```
+   npm install
+   ```
+
+3. Start the development server:
+   ```
+   npm run dev
+   ```
+
+   This will start the Vite development server. The application should now be running at `http://localhost:<port>`
+
+## Project Structure
+
+```
+web/exporer/
+├── src/
+│   ├── assets/
+│   ├── components/
+│   ├── composables/
+│   ├── router/
+│   ├── utils/
+│   ├── views/
+│   ├── App.vue
+│   └── main.js
+├── public/
+├── tests/
+├── index.html
+├── package.json
+├── vite.config.js
+├── DEVELOPMENT.md
+└── README.md
+```
+
+- `src/`: Contains the source code of the application
+- `src/components/`: Reusable Vue components
+- `src/composables/`: Vue composition functions
+- `src/router/`: Vue Router configuration
+- `src/utils/`: Utility functions
+- `src/views/`: Top-level views/pages
+- `src/tests/`: Test files
+- `public/`: Static assets that will be served as-is
+
+## Building for Production
+
+To build the application for production:
+
+```
+npm run build
+```
+
+This will generate production-ready files in the `dist/` directory.
+
+## Testing
+
+Run the test suite with:
+
+```
+npm run test
+```
+
+We use Vitest as our testing framework. Please ensure all tests pass before submitting a pull request.
+
+## Linting and Formatting
+
+We use ESLint for linting and Prettier for code formatting. Run the linter with:
+
+```
+npm run lint
+```
+
+To automatically fix linting and formatting issues:
+
+```
+npm run lint:fix
+```
+
+## Working with PrimeVue Components
+
+Capa Explorer WebUI uses the PrimeVue UI component library. When adding new features or modifying existing ones, refer to the [PrimeVue documentation](https://www.primefaces.org/primevue/) for available components and their usage.
+
+## Best Practices
+
+1. Follow the Vue.js Style Guide for consistent code style.
+3. Document new functions, components, and complex logic.
+4. Write tests for new features and bug fixes.
+5. Keep components small and focused on a single responsibility.
+6. Use composables for reusable logic across components.
+
+## Additional Resources
+
+- [Vue.js Documentation](https://vuejs.org/guide/introduction.html)
+- [Vite Documentation](https://vitejs.dev/guide/)
+- [PrimeVue Documentation](https://www.primefaces.org/primevue/)
+
+If you encounter any issues or have questions about the development process, please open an issue on the GitHub repository.
diff --git a/web/explorer/README.md b/web/explorer/README.md
index c7e09273..36db043c 100644
--- a/web/explorer/README.md
+++ b/web/explorer/README.md
@@ -38,4 +38,4 @@ We welcome your feedback and contributions to improve the web-based Capa Explore
 
 ---
 
-For developers interested in building or contributing to Capa Explorer WebUI, please refer to our [Development Guide](CONTRIBUTION.md).
+For developers interested in building or contributing to Capa Explorer WebUI, please refer to our [Development Guide](DEVELOPMENT.md).