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 for bug fixes or minor changes.

    • 2.0 for new features.

  2. Create a Topic Branch

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

      git switch upstream/2.0 -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.0  # or upstream/1.14 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.0
      git push --force-with-lease origin feature_branch
  2. Squash Commits

    • To squash commits, rebase interactively:

      git rebase -i upstream/2.0
    • Replace pick with squash or s for all but the first commit, then save and push:

      git push --force-with-lease origin feature_branch

Last updated

© 2024 Sylius. All Rights Reserved