Skip to content

Latest commit

 

History

History
242 lines (169 loc) · 8.1 KB

CONTRIBUTING.md

File metadata and controls

242 lines (169 loc) · 8.1 KB

Contributing Guide

Thank you for considering contributing to the Time Tool project! This guide provides instructions for setting up your development environment and guidelines for contributing effectively.

Table of Contents

Developer Tools

Ensure you have the following tools installed:

Project Setup

  1. Clone the Repository:

    git clone [email protected]:YournameITManoah/time-tool.git
cd time-tool

  2. Install PHP Dependencies:

    composer install

  3. Install Node.js Dependencies:

    npm install

  4. Set Up Environment Variables:

    • Duplicate .env.example and rename it to .env.
    • Configure the necessary environment variables, such as database credentials.

  5. Generate Application Key:

    php artisan key:generate

  6. Run Database Migrations:

    Ensure your database is set up and configured in the .env file.

    php artisan migrate

  7. Start the Development Vite Server:

    npm run dev

  8. Start the Development PHP Server:

    php artisan serve

    Access the application at http://127.0.0.1:8000/.

Working with Laravel

  • Configuration: located in app/Providers/AppServiceProvider.php and config.
  • Controllers, Middleware and Form Requests: Located in app/Http.
  • Models: Located in app/Models.
  • Policies: Located in app/Policies.
  • Rules: Located in app/Rules.
  • Factories, migrations and seeders: Located in database.
  • Localization: Defined in the lang directory.
  • Public Assets: Defined in the public directory.
  • Routing: Defined in the routes directory.

Refer to the Laravel documentation for detailed information.

Working with Hybridly

Hybridly enhances the integration between Laravel and Vue.js, providing features like partial reloads, forms, dialogs, and more.

  • Installation: Hybridly is already installed in the project.
  • Configuration: located in config/hybridly.php and app/Http/Middleware/HandleHybridRequests.php.
  • Usage: Refer to the Hybridly documentation for detailed usage instructions.

Working with Vue.js

  • Application configuration: Located in resources/application.
  • Assets, components, composables, layouts, types, utils and views: Located in resources.
  • State Management: Managed using Pinia, with store files in resources/stores.
  • UI: UI is created with Vuetify components and Material Design Icons.

Refer to the Vue.js documentation for more information.

Working with Filament

Filament is used for building the admin panel.

  • Configuration: Located in app/providers/Filament/AdminPanelProvider.php.
  • Exporters: Located in app/Filament/Exports.
  • Resources: Located in app/Filament/Resources.
  • Pages: Located in app/Filament/{Resource}/Pages.
  • Relation Managers: Located in app/Filament/{Resource}/RelationManagers.

Refer to the Filament documentation for detailed information.

Localization

Localization files are located in the lang directory. Each language has its own subdirectory containing PHP translation files. These are used by Laravel for validation messages, for example. Each language, except English, also has a json file which contains translations for the frontend of the application and for the frontend of the Filament admin panel.

New locale

To add a new locale, you need to first copy lang/en to lang/{locale} and lang/nl.json to lang/{locale}.json. Then modify the translations strings of the newly created files. When a locale is ready for release you need to define it in three places:

  1. app/SupportedLocale.php

    enum SupportedLocale: string
{
    case ENGLISH = 'en';
    case DUTCH = 'nl';
    // New locale here
}

  2. config/app.php

    'locales' => [
        'en' => 'English',
        'nl' => 'Nederlands',
        // New locale here
    ]

  3. resources/application/vuetify.ts

    import DateFnsAdapter from '@date-io/date-fns'
import { enUS as enDateFns } from 'date-fns/locale/en-US'
import { nl as nlDateFns } from 'date-fns/locale/nl'
// Import date-fns language pack for new locale here

const vuetify = createVuetify({
    date: {
        adapter: DateFnsAdapter,
        locale: {
            en: enDateFns,
            nl: nlDateFns,
            // New locale here
        },
    },
})

Finally, you need to add a flag, representing the language, to the public assets (public/img/flags/{locale}.svg). You can retrieve flags from the Blade Flags repository.

Code Style Guidelines

  • PHP: Follow the PSR-12 coding standard.
  • JavaScript: Follow the recommended JavaScript, TypeScript and Vue rules, enforced by eslint.

Ensure your code is properly formatted before submitting. You can use tools like PHP CS Fixer for PHP and ESLint for JavaScript to automate code formatting.

Commit Message Guidelines

Commit messages should be completely lowercase and be written in the imperative form (e.g. add this or fix that).

  • Format: Use the following structure:

    type(scope?): short description

  • Types:

    • feat: For new features.
    • fix: For bug fixes.
    • refactor: For code refactoring.
    • docs: For documentation updates.
    • style: For code style changes.
    • test: For adding or updating tests.
    • chore: For maintenance that does not change the actual code (e.g. dep updates).
    • ci: For changes to the CI workflows.

  • Scopes

    Scopes are not required, but can improve the clarity of the commit message, common scopes include: deps, i18n, api, auth, admin.

  • Examples:

    feat(i18n): add Spanish locale
    fix: validate duplicate time logs
    chore(deps): update composer packages

Submitting Contributions

  1. Fork the Repository: Click the "Fork" button on the repository's GitHub page.

  2. Create a New Branch:

    git checkout -b feat/your-feature-name

  3. Make Changes: Implement your changes, adhering to the code style guidelines.

  4. Commit Changes: Write clear and concise commit messages following the commit message guidelines.

  5. Push to Your Fork: Push your changes to your forked repository.

    git push origin feat/your-feature-name

  6. Open a Pull Request: Go to the original repository and open a pull request with a description of your changes.

Thank you for your contributions!