Skip to main content

Contributing to Documentaion

Contributions to the Vecros User Guide are very welcome; from simple fixes to spelling and grammar, through to the creation of whole new sections.

This topic explains how to make and test changes. Towards the end there is a basic style guide.

note

You will need a (free) Github account to contribute to the guides.

Changes using Git (New Pages and Images)​

More substantial changes, including adding new pages or adding/modifying images, aren't as easy to make (or properly test) on Github. For these kinds of changes we suggest using the same approach as for code:

  1. Use the git toolchain to get the documentation source code onto your local computer.
  2. Modify the documentation as needed (add, change, delete).
  3. Test that it builds properly using Vitepress.
  4. Create a branch for your changes and create a pull request (PR) to pull it back into the documentation.

The following explain how to get the source code, build locally (to test), and modify the code.

Get/Push Documentation Source Code​

To get the library(s) sources onto your local computer you will need to use the git toolchain. The instructions below explain how to get git and use it on your local computer.

  1. Download git for your computer from https://git-scm.com/downloads

  2. Sign up for Github if you haven't already

  3. Create a copy (Fork) of the VECROS User Guide repo on Github (instructions here).

  4. Clone (copy) your forked repository to your local computer:

    cd ~/wherever/
    git clone https://github.com/<your git name>/docs_vecros_com.git

    For example, to clone the Vecros userguide fork for a user with Github account "vecros-tech":

    git clone https://github.com/vecros-tech/docs_vecros_com.git

  5. Navigate to your local repository:

    cd ~/wherever/docs_vecros_com

  6. Add a remote called "upstream" to point to the Vecros version of the library:

    git remote add upstream https://github.com/vecros-tech/docs_vecros_com.git
    tip

    A "remote" is a handle to a particular repository. The remote named origin is created by default when you clone the repository, and points to your fork of the guide. Above you create a new remote upstream that points to the Vecros project version of the documents.

  7. Create a branch for your changes:

    git checkout -b <your_feature_branch_name>

    This creates a local branch on your computer named your_feature_branch_name.

  8. Make changes to the documentation as needed (general guidance on this in following sections)

  9. Once you are satisfied with your changes, you can add them to your local branch using a "commit":

    git add <file name>
    git commit -m "<your commit message>"

    For a good commit message, please refer to the Source Code Management section.

  10. Push your local branch (including commits added to it) to your forked repository on Github.

    git push origin your_feature_branch_name

  11. Go to your forked repository on Github in a web browser, e.g.: https://github.com/<your git name>/docs_vecros_com.git. There you should see the message that a new branch has been pushed to your forked repository.

  12. Create a pull request (PR):

  • On the right hand side of the "new branch message" (see one step before), you should see a green button saying "Compare & Create Pull Request". Press it.
  • A pull request template will be created. It will list your commits and you can (must) add a meaningful title (in case of a one commit PR, it's usually the commit message) and message (explain what you did for what reason. Check other pull requests for comparison)
  1. You're done! Maintainers for the Vecros User Guide will now have a look at your contribution and decide if they want to integrate it. Check if they have questions on your changes every once in a while.