> Markdown version of [Submitting Documentation](https://vaadin.com/docs/v23/contributing-docs/authoring/submitting). Section index: [llms.txt](https://vaadin.com/docs/v23/contributing-docs/llms.txt)

# Submitting Documentation

To submit additions or corrections to Vaadin documentation, you need to create a pull request in the [Vaadin Docs GitHub repository](https://github.com/vaadin/docs).

See [Contributing to Projects](https://vaadin.com/docs/v23/contributing/overview.md) 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.

## <a id="making-a-pull-request"></a>Making a Pull Request

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

### <a id="contributors"></a>Contributors

As a contributor, you need to:

1. Fork the [`https://github.com/vaadin/docs`](https://github.com/vaadin/docs) repository in GitHub.

2. Clone it locally to edit it.

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

3. Make a new branch for the improvements.

   ```terminal
   git checkout -b my-feature-branch
   ```

4. Make the changes.

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

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

   ```terminal
   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.

   ```terminal
   git add ...
   git commit -m "Fixes from review"
   git push
   ```

### <a id="vaadin-developers"></a>Vaadin Developers

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

1. Clone the [`https://github.com/vaadin/docs`](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](https://github.com/vaadin/docs) 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.

## <a id="labeling"></a>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.

## <a id="requirements-for-merging"></a>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

## <a id="merging"></a>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`
