Skip to content

Latest commit

 

History

History
182 lines (128 loc) · 5.8 KB

CONTRIBUTING.md

File metadata and controls

182 lines (128 loc) · 5.8 KB

Contributing to WISdoM Frontend

Thank you for contributing to the WISdoM frontend project! This document outlines everything you need to know to get started and contribute effectively.

About the Project

This repository contains the entire frontend source code for the WISdoM project. All previous frontend-* repositories have been archived in favor of a monolithic structure, which Angular supports better than a multi repo. We use Angular as it provides a robust and structured approach to web development compared to libraries like React or Vue. Though the learning curve may be steep, the final codebase remains clean and maintainable.

We use Bulma as our CSS framework. It's lightweight, JS-free, and easy to integrate. Some additional behavior is built around Bulma; check:

  • src/variables.scss: for custom variables.
  • src/common/directives/: for Bulma-compatible Angular directives.

Development Tools

Node and NPM

  • Use Volta to manage your Node version. Do not install Node manually. Volta can also install a global Node version, so don't be scared.

  • Install project dependencies via:

    npm install

VSCode Setup

If you want to use VSCode, make sure you check out the .vscode directory for helpful preconfigured settings.

Recommend Extensions:

  • Angular Language Service: Angular code assistance.
  • Todo Tree: List all TODOs across the project.
  • Thunder Client: API endpoint testing.
  • Pretty TypeScript Errors: Readable TS error messages.
  • Scope to This: Simplifies file navigation in large projects.

VSCode Settings:

  • cSpell.language: Set to en and de for mixed English-German strings.
  • typescript.tsdk: Uses workspace TypeScript for TOML support.

NPM Scripts

Run scripts via npm run. Key scripts include:

  • start: Start local development server.
  • build: Build the application for production.
  • lint: Run the linter.
  • fmt: Format the codebase.
  • doc: Generate documentation.

Ensure you run lint and fmt before pushing. The CI enforces this.

Git Pre-Commit Hooks

In order to automatically format and lint the codebase, you can use husky (https://typicode.github.io/husky/get-started.html) install via

npm install --global husky

and make sure npm still functions with repeating

npm install

Then, whenever you commit anything via git or GitHub Desktop, both scripts get executed before the commit happens and you don't have to do so manually

Code Organization

File and Directories

Key directories:

  • public: Static files copied directly into dist for hosting.
  • src: Application code, split into:
    • api: Services for backend API interaction.
    • common: Shared components, utilities, and tools (highly documented).
    • core: Authentication, app frame, and core utilities.
    • modules: Individual feature modules (most work happens here).
    • types: Additional type definitions.
    • Important Files:
      • config.ts: App configuration.
      • i18n.ts: Configures translation files and namespaces for the application.
      • routes.ts: Application routes.
      • proxy.conf.json: Local API proxy for development.
      • styles.scss: Global styles.
      • variables.scss: Shared Bulma variables.

Building a New Module

  1. Familiarize with Angular:

  2. Workspace Setup:

    • Create a new directory in src/modules for your feature.
    • Avoid generating unnecessary files.

  3. API Integration:

    • Add new services in src/api.
    • Use src/common/http-contexts.ts for HTTP contexts.
    • Validate responses using AJV and httpContexts.validateSchema.

  4. Components:

  5. Translations:

  6. Custom Signals:

    • Check src/common/signals.ts for existing signals before creating new ones.

  7. Styling:

    • Use Bulma for consistency.
    • Import variables.scss if you need Bulma variables or shared styles.

  8. Exports:

    • Each file should export a single symbol for better namespace management.
    • Use the namespace keyword to group multiple symbols under one export.

  9. Routing:

  • Add routes to src/routes.ts, usually as a child for the "" route.
  • Make the route accessible by adding a routerLink to src/core/sidebar/sidebar.component.html.

License

The project is licensed under the EUPL-1.2. Ensure any dependencies are compatible. Most MIT and Apache-licensed packages are fine.

Final Notes

Before submitting a PR:

  • Run npm run lint and npm run fmt to pass CI checks. (see ## Git Pre-Commit Hooks above)
  • Ensure your module aligns with the project's structure and standards.
  • Familiarize yourself with src/common — it might already contain what you need.

Happy coding! 🚀