Contribution Guide

Contributions to BladewindUI are very much welcome. A good place to find something to contribute will be our GitHub issues page or our development roadmap. Any discussion that contains anything feature-worthy will already have a corresponding issue.

Bug Reports and Questions

To help us keep all bug reports and questions consolidated, and to also serve as a reference for others who might have the same questions or reports, we encourage you to post all questions and bug reports on our GitHub issues page. Bug reports should be descriptive enough to be reproducible. It is good practice to include the following in your bug report.

• BladewindUI version number
• PHP version
• OS
• Browser type and version

Pull Requests and Branching

Before working on a feature or issue, we encourage you to take a look at our GitHub issues page to ensure you are not planning to work on something already in progress or that has already been closed and probably awaiting a merge into main. Every issue or feature being worked on will have an assignee. Any issue without an assignee can be picked up and worked on by anyone.

To work on an issue that is not listed, kindly create the issue on our GitHub issues page and assign to yourself. In fact, the rule of thumb is to assign any issue you decide to work on to yourself. That is how the community knows what is in progress.

For changes that address core functionality or would require breaking changes (e.g. a major release), it is best to open an Issue to discuss your proposal first. This is not a must but can save time creating and reviewing changes down the line.

In general, BladewindUI follows the "fork-and-pull" Git workflow

• Fork the repository to your own Github account.
• Clone the project to your machine.
• Create a local branch (from the development branch) with an issue prefix followed by issue number. If what you are working on does not exist on our issues page, please create the issue. If what intend to work on is a feature from our roadmap, still create the issue and assign the enhancement label to it.
• Commit changes to the branch following the formatting guidelines specific to this repo (yet to implement StyleCI).
• Push changes to your fork.
• Open a PR against mkocansey/bladewind repository, development branch.
• Once the PR is reviewed and accepted, it will be merged. The code will then make its way into the main branch and then a release.

Compiled Assets

There are a couple of CSS and JavaScript assets available in the BladewindUI codebase. We encourage contributors to make changes to the source css file but not submit a compiled css file. This makes it easier to review what has been added as css.

If you are working on a new component from our roadmap that requires some CSS, you can either define these inline or have a dedicated CSS file in the resources/assets/css directory, where all the other component styles live.

Testing Locally

It is much easier to test whatever you are working on locally to ensure everything is working as intended. To this end, you will need to include a local version of BladewindUI in a project you can test locally.

You will need to make the following modifications to your project's composer.json file. This is the project you are testing the BladewindUI changes in.

        
        // your-project/composer.json
        ...
        "require": {
            ...
            /*
            issue-184 is the name of the Bladewind branch
            you either checked out or created
            dev- is just a prefix required by composer
            if you checked out the development branch,
            you will type "dev-development"
            */
            "mkocansey/bladewind": "dev-issue-184",
            ...
        },
        "repositories": {
            "mkocansey/bladewind": {
                "type": "path",
                "url": "/path/to/bladewind/folder/on/your/computer"
                // on my computer, the value for url is
                //  "/Users/mkocansey/projects/kursor/bladewind"
            }
        }
        
    

Now you will need to run composer update at the root of your project.

composer update

Your project should be using your local version of BladewindUI now. To test the components directly from the vendor/mkocansey directory, use the colon notation for invoking components.

    <x-bladewind::bell />
    <x-bladewind::notification />
    

If you are making CSS or Javascript changes, you will need to be compiling the TailwindCSS classes as you code. I use mix for this but you can stick with however you already compile assets.

# this should be run at the root
# of your local version of bladewind
npx mix watch

php artisan vendor:publish --provider="Mkocansey\Bladewind\BladewindServiceProvider" --tag=bladewind-public --force

Documenting New Attributes or Components

This is an optional step. As much as possible I will document any changes that come in the PRs. If you however, introduce new attributes or components and want to take a stab at documenting them, you will need to clone the the documentation code to your computer. This is a Laravel project not markdown files unfortunately.

Contributing to the documentation follows the same steps outlined above .

Coding Style

BladewindUI adheres to the PSR-2 coding standards as well as the PSR-4 autoloading standards.

All props should be at top of the page and variables should be of the right type.

        
        props([
        'size'       => 'small',
        'show_dot'   => true,       // correct
        'show_dot'   => 'true',     // wrong
        ...
        
    

Attribute Names

As much as possible, try to use single words for attribute names where possible. Where you need to use more than one word, the attribute names should read like spoken English. Especially if the attribute values will be boolean. Below are a couple of examples.

        
        props([
        'show_dot'   => true,
        'has_shadow' => true,
        'accepted_file_types' => '',
        'is_numeric' => true,   // this can just be 'numeric' => true,
        'show_close_icon' => true,

        // the above attribute can be replaced with the one word
        'closable' => true,
        ...
        
    

Code of Conduct

BladewindUI derives its code of conduct from The Ruby Community Conduct Guideline and we advise contributors to be respectful of these.

• Participants will be tolerant of opposing views.
• Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
• When interpreting the words and actions of others, participants should always assume good intentions.
• Behaviour which can be reasonably considered harassment will not be tolerated.