Documentation

You are viewing documentation for Vaadin 23. View latest documentation

Documentation

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.

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

  3. Make a new branch for the improvements.

    git checkout -b my-feature-branch

  4. Make the changes.

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

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

    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.

    You don’t need to set the upstream again, but can git push the changes.

    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 jouni for documentation style review, or ask to do separately outside the development time box.

    • No dedicated proofreader is currently available, but jouni 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.

Labeling

A pull request is automatically labeled with AsciiDoc, Java, and TypeScript according to the files included in the pull request. Check that the action has set the labels correctly. Once each content type has been reviewed, the labels should be changed to AsciiDoc OK, Java OK, and TypeScript OK, respectively. This enables having multiple reviewers with different tasks.

Requirements for Merging

Merging a pull request has the following requirements:

  • Labels AsciiDoc, Java, and TypeScript must have been resolved to AsciiDoc OK, Java OK, and TypeScript OK, respectively.

  • The PR must have been accepted in review (admin can merge at any time if the above labels are OK).

  • 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’s reviewed and all checks are successful. A reviewer shouldn’t merge the PR, unless it’s obvious that the author doesn’t have more upcoming additions. This gives the possibility to get comments for new documentation, while keeping on writing it.

7B183C97-BC2C-499C-8389-43B6B7B03A72