Submitting a Patch

Patches are the best way to submit bug fixes or propose enhancements to Sylius. Here’s a step-by-step guide.

Step 1: Set Up Your Environment

1. Install Required Software

   • Git

   • PHP (version 8.1 or above)

   • MySQL

2. Configure Git

   • Set up your name and email:

     git config --global user.name "Your Name"
     git config --global user.email "[email protected]"

   Windows Users: During Git setup, select the “as-is” option for line endings to avoid issues. You can verify and correct this by running:

   git config core.autocrlf input

3. Get the Sylius Source Code

   • Fork the Sylius repository on GitHub.

   • Clone your fork:

     git clone [email protected]:YOUR_USERNAME/Sylius.git

   • Add the main Sylius repository as an upstream remote:

     cd Sylius
     git remote add upstream git://github.com/Sylius/Sylius.git

New to Git? Check out the free ProGit book for guidance.

Step 2: Develop Your Patch

1. Choose the Base Branch

   • 1.14/2.1 for bug fixes or minor changes.

   • 2.2 for new features.

2. Create a Topic Branch

   • Start your work on a dedicated branch, based on the chosen branch:

     git switch upstream/2.2 -c feature_branch

   Tip: Use descriptive names for branches (e.g., issue-123 for a fix related to issue #123).

3. Develop Your Patch

   • Follow BDD and coding standards (check for trailing spaces with git diff --check).

   • Keep commits atomic and logically organized.

   • Squash minor fix commits (e.g., typo corrections).

   • Avoid changing coding standards in existing files (submit those as separate patches).

4. Write Clear Commit Messages

   • Format: [Component] Fixed issue ...

   • Include a summary on the first line, followed by details if needed.

Step 3: Prepare for Submission

1. Rebase Your Patch

   • Before submitting, ensure your branch is up-to-date:

     git checkout feature_branch
     git rebase upstream/2.2  # or upstream/2.1 for bug fixes

   • Resolve any conflicts and continue the rebase:

     git add resolved_file
     git rebase --continue

2. Push Your Branch

   • Push your changes to your fork:

     git push --force-with-lease origin feature_branch

3. Create a Pull Request

   • Open a pull request on the Sylius GitHub repository.

   • Title: Include relevant components (e.g., [Cart] Fixed bug ...).

   • Checklist: Include the following table in the PR description:

     | Q               | A
     | --------------- | -----
     | Branch?         | {lowest_bugfix_version} or {future_version}
     | Bug fix?        | no/yes
     | New feature?    | no/yes
     | BC breaks?      | no/yes
     | Deprecations?   | no/yes
     | Related tickets | fixes #X, partially #Y, mentioned in #Z
     | License         | MIT

If your PR is unfinished, add [WIP] to the title and list any tasks still in progress.

Step 4: Make Requested Changes

After submitting, you may receive feedback. Here’s how to make adjustments:

1. Rebase with Your Base Branch

   • Rebase instead of merging, and push again:

     git rebase -f upstream/2.2
     git push --force-with-lease origin feature_branch

2. Squash Commits

   • To squash commits, rebase interactively:

     git rebase -i upstream/2.2

   • Replace pick with squash or s for all but the first commit, then save and push:

     git push --force-with-lease origin feature_branch