• Before Your First Contribution
• Fast Online Contributions
• Your First Documentation Contribution
• Your Next Documentation Contributions
• Review your changes
• Frequently Asked Questions
  • Why Do My Changes Take So Long to Be Reviewed and/or Merged?
  • Why Should I Use the Oldest Maintained Branch Instead of the Latest Branch?
  • What If I Want to Submit my Work without Fully Finishing It?
  • Would You Accept a Huge Pull Request with Lots of Changes?

Before Your First Contribution

Before contributing, you need to:

• Sign up for a freeGitHub account, which is the service where the Symfonydocumentation is hosted.
• Be familiar with thereStructuredText markup language, which is used towrite Symfony docs. Readthis articlefor a quick overview.

Fast Online Contributions

If you're making a relatively small change - like fixing a typo or rewordingsomething - the easiest way to contribute is directly on GitHub! You can do thiswhile you're reading the Symfony documentation.

Step 1. Click on theedit this page button on the top of the pageand you'll be redirected to GitHub:

Step 2. If this is your first contribution, you have to fork the repository.Then, edit the contents, preview your changes (with the button at the top left)and click on theCommit changes... button. In the popup, describe your changesand click onPropose changes button.

Step 3. GitHub will now create a branch and a commit for your changes and it willalso display a preview of your changes:

If everything is correct, click on theCreate pull request button.

Step 4. GitHub will display a new page where you can do some last-minutechanges to your pull request before creating it. For simple contributions, youcan safely ignore these options and just click on theCreate pull requestbutton again.

Congratulations! You just created a pull request to the official Symfonydocumentation! The community will now review your pull request and (possibly)suggest tweaks.

If your contribution is large or if you prefer to work on your own computer,keep reading this guide to learn an alternative way to send pull requests to theSymfony Documentation.

Your First Documentation Contribution

In this section, you'll learn how to contribute to the Symfony documentation forthe first time. The next section will explain the shorter process you'll followin the future for every contribution after your first one.

Let's imagine that you want to improve the Setup guide. In order to make yourchanges, follow these steps:

Step 1. Go to the official Symfony documentation repository located atgithub.com/symfony/symfony-docs and click on theFork button tofork the repository to your personal account. This is only needed the firsttime you contribute to Symfony.

Step 2.Clone the forked repository to your local machine (this exampleuses theprojects/symfony-docs/ directory to store the documentation; changethis value accordingly):

12

$cd projects/$gitclone git@github.com:YOUR-GITHUB-USERNAME/symfony-docs.git

Step 3. Add the original Symfony docs repository as a "Git remote" executingthis command:

12

$cd symfony-docs/$git remote add upstream https://github.com/symfony/symfony-docs.git

If things went right, you'll see the following when listing the "remotes" ofyour project:

12345

$git remote -vorigin  git@github.com:YOUR-GITHUB-USERNAME/symfony-docs.git (fetch)origin  git@github.com:YOUR-GITHUB-USERNAME/symfony-docs.git (push)upstream  https://github.com/symfony/symfony-docs.git (fetch)upstream  https://github.com/symfony/symfony-docs.git (push)

Fetch all the commits of the upstream branches by executing this command:

1

$git fetch upstream

The purpose of this step is to allow you to work simultaneously on the officialSymfony repository and on your own fork. You'll see this in action in a moment.

Step 4. Create a dedicatednew branch for your changes. Use a short andmemorable name for the new branch (if you are fixing a reported issue, usefix_XXX as the branch name, whereXXX is the number of the issue):

1

$git checkout -b improve_install_article upstream/6.4

In this example, the name of the branch isimprove_install_article and theupstream/6.4 value tells Git to create this branch based on the6.4branch of theupstream remote, which is the original Symfony Docs repository.

Fixes should always be based on theoldest maintained branch which containsthe error. Nowadays this is the6.4 branch. If you are instead documenting anew feature, switch to the first Symfony version that included it, e.g.upstream/7.2.

Step 5. Now make your changes in the documentation. Add, tweak, reword andeven remove any content and do your best to comply with theDocumentation Standards. Then commit your changes!

123

# if the modified content existed before$git add setup.rst$git commit setup.rst

Step 6.Push the changes to your forked repository:

1

$git push origin improve_install_article

Theorigin value is the name of the Git remote that corresponds to yourforked repository andimprove_install_article is the name of the branch youcreated previously.

Step 7. Everything is now ready to initiate apull request. Go to yourforked repository athttps://github.com/YOUR-GITHUB-USERNAME/symfony-docsand click on thePull Requests link located in the sidebar.

Then, click on the bigNew pull request button. As GitHub cannot guess theexact changes that you want to propose, select the appropriate branches wherechanges should be applied:

In this example, thebase fork should besymfony/symfony-docs andthebase branch should be the4.4, which is the branch that you selectedto base your changes on. Thehead fork should be your forked copyofsymfony-docs and thecompare branch should beimprove_install_article,which is the name of the branch you created and where you made your changes.

Step 8. The last step is to prepare thedescription of the pull request.A short phrase or paragraph describing the proposed changes is enough to ensurethat your contribution can be reviewed.

Step 9. Now that you've successfully submitted your first contribution tothe Symfony documentation,go and celebrate! The documentation managerswill carefully review your work in short time and they will let you know aboutany required change.

In case you are asked to add or modify something, don't create a new pullrequest. Instead, make sure that you are on the correct branch, make yourchanges and push the new changes:

123456

$cd projects/symfony-docs/$git checkout improve_install_article# ... do your changes$git push

It's rare, but you might be asked to rebase your pull request to target anotherSymfony branch. Read theguide on rebasing pull requests.

Step 10. After your pull request is eventually accepted and merged in theSymfony documentation, you will be included in theSymfony Documentation Contributors list. Moreover, if you happen to have aSymfonyConnectprofile, you will get a coolSymfony Documentation Badge.

Your Next Documentation Contributions

Check you out! You've made your first contribution to the Symfony documentation!Somebody throw a party! Your first contribution took a little extra time becauseyou had to learn a few standards and set up your computer. But from now on,your contributions will be much easier to complete.

Here is achecklist of steps that will guide you through your nextcontribution to the Symfony docs:

12345678910111213141516171819

# create a new branch based on the oldest maintained version$cd projects/symfony-docs/$git fetch upstream$git checkout -b my_changes upstream/6.4# ... do your changes# (optional) add your changes if this is a new content$git add xxx.rst# commit your changes and push them to your fork$git commit xxx.rst$git push origin my_changes# ... go to GitHub and create the Pull Request# (optional) make the changes requested by reviewers and commit them$git commit xxx.rst$git push

After completing your next contributions, also watch your ranking improve onthe list ofSymfony Documentation Contributors. You guessed right: after allthis hard work, it'stime to celebrate again!

Review your changes

Symfony repository checks every Pull Request automatically to look for commonerrors, inappropriate words, syntax issues in code blocks, etc.

Optionally you can also build the docs in your local machine to debug issues orto read the documentation offline. To do so, follow the instructions included inthe README file of symfony-docs repository.

Frequently Asked Questions