Submitting Documentation

To submit additions or corrections to Vaadin documentation, you need to create a pull request in the Vaadin Docs GitHub repository.

See Contributing to Projects for general instructions on contributing to Vaadin. You should separate enhancements, fixes, and new features into different pull requests. Check your changes for basic style violations.

Making a Pull Request

To submit a contribution, you need to create a feature branch and push that for review.

Contributors

As a contributor, you need to:

1. Fork the https://github.com/vaadin/docs repository in GitHub.

2. Clone it locally to edit it.

   Show code

   bash

   Expand code

   $ git clone https://github.com/vaadin/docs.git

3. Make a new branch for the improvements.

   Show code

   bash

   Expand code

   $ git checkout -b my-feature-branch

4. Make the changes.

   Show code

   bash

   Expand code

   $ git add [files]
   $ git commit -m "Fixed several typos in Flow documentation"

5. Push the changes to the branch in your forked repository.

   Show code

   bash

   Expand code

   $ git push --set-upstream origin submitting-to-docs

6. Create a pull request in the Docs repository.

   1. Open the your fork repository page at GitHub in browser.

   2. Your change should show there.

      Click Compare & pull request.

   3. In the Open a pull request form, enter a title for the PR, an optional comment, and click Create pull request.

7. Make and push fixes requested in the review.

   Note that you do not need to set the upstream again, but can just git push the changes.

   Show code

   bash

   Expand code

   $ git add ...
   $ git commit -m "Fixes from review"
   $ git push

Vaadin Developers

Vaadin developers with write access to the Docs repository should (like above):

1. Clone the https://github.com/vaadin/docs repository to edit it.

2. Make a new branch for the improvements.

3. Make the changes.

   • Preview locally while writing.

4. Push the changes to the new branch in the Docs repository.

5. Create a pull request in the Docs repository.

   1. Open the Docs repository page in browser.

   2. Your change should show there.

      Click Compare & pull request.

   3. In the Open a pull request form, enter a title for the PR, an optional comment, and click Create pull request.

6. Add reviewers

   • Review in the development team.

   • Component code examples (TypeScript and Java) need to be approved by tomivirkki, DiegoCardoso, or yuriy-fix.

   • Can add magi42 for documentation style review, or ask to do separately outside the development time box.

   • No dedicated proofreader is currently available, but magi42 can be asked for review.

7. Make fixes requested in the review.

8. Merge the PR by yourself or have the team lead or main author do it.

Requirements for Merging

Merging a pull request has the following requirements:

• The PR must have been accepted in review

• Deployment preview build must finish successfully

• You must have signed the Contributor License Agreement

The following requirements are optional and not enforced:

• Vale checks are successful

Merging

For contributions, the reviewer merges the pull request once it has been approved.

Vaadin developers with write access to the repository are able to merge their own pull request once it is reviewed and all checks are successful. A reviewer should not merge the PR, unless it is obvious that the author does not have more upcoming additions. This gives the possibility to get comments for new documentation, while keeping on writing it.