Xenial.Framework

# Contribute to Documentation locally

If you prefer to work in local environment with the benefits of syntax highlighting, spell checking, version control and visual feedback, it is possible to do so and the contributions that you make can then be submitted via the process know as 'Pull Requests'.

This requires a little bit more setup, but if you are a developer most of the required tools are probably installed on your machine anyway.

# Technology stack

We use the following tools to write, build and deploy the documentation.

The documents are written in markdown (opens new window) to allow for easy versioning and consistent styling.

You can use a text-editor or IDE of your choice. Visual Studio Code VSCode (opens new window) is recommended because it provides a couple of handy extensions that help with writing documentation.

# Prerequisites

CAUTION

If the tools mentioned above are already installed please ensure that they are up to date with the latest releases. Failure to do this may mean that it is impossible to build the documentation without encountering errors.

TIP

If you do not have a Git Hub account (opens new window) this would be the ideal time to set one up.

CAUTION

When setting up a new Git Hub account choose your username carefully. It is notoriously difficult to change at a later date.

# Clone the sources

First of all you need to fork the repository (opens new window) on github (opens new window).

Fork the repository

Afterwards you need to clone the repository from your fork. To do that you need to copy your url under the code button.

Fork the repository

git clone https://github.com/YOUR_GITHUB_NAME/Xenial.Framework.git
1

If you never worked with git before, its necessary to set your name and email address to start contributing:

git config --global user.email "you@example.com"
git config --global user.name "Your Name"
1
2

In order to be able to keep your fork in sync with the Xenial.Framework main repository it is necessary to set an upstream:

git remote add upstream https://github.com/xenial-io/Xenial.Framework.git
1

# Build the documentation

After cloning the repository you need to change the directory and call the b.bat file with the arguments docs. This will restore all the external dependencies and build the documentation.

b.bat docs
1

TIP

You can list all available targets using the b.bat -l command.

# Live preview

You can edit the documentation with help of live preview. This is useful because you get immediate feedback after hitting save, as it automatically refreshes the content without the need to refresh the browser manually.

b.bat docs:serve
1

This will build the local documentation and launch a local server and browser window at the following address http://127.0.0.1:8080/ (opens new window).

TIP

You can edit all *.md content.
If you edit .vuepress/config.js or any frontmatter (opens new window) you need to restart the server by hitting ctrl+c to stop the server and confirming the kill by hitting [Y]es twice.

# Editing the documentation

To edit the documentation using VSCode open the subdirectory ./docs:

code docs
1

After you have made your changes to the source document, you can commit them using VSCode:

Commit changes

Or using the commandline:

git add .
git commit -m "docs: your commit message"
1
2

TIP

The docs: prefix in the commit message helps with generating a semantic changelog.

After committing you need to 'push' your changes to your repository. This can be done in VSCode:

Sync the repository

Or using the commandline:

git push
1

# Keep your fork in sync

Because GIT is a decentralized version control system, you have a complete historical copy of all of the changes you have made, hence the name clone.
This means you need to keep your GIT repository in sync with the original upstream (opens new window) repository.

First you make sure that your repository has no uncommitted changes

git status

# 
# On branch main
# Your branch is up to date with 'origin/main'.
# 
# nothing to commit, working tree clean
#
1
2
3
4
5
6
7
8
git fetch upstream
git checkout main
git merge upstream/main
1
2
3

TIP

If you have already cloned the repository it is possible that you may have missed a step so, just as a gentle reminder: you must have configured your upstream at this stage:

git remote add upstream https://github.com/xenial-io/Xenial.Framework.git
1

Learn more about keeping repositories in sync over at github docs (opens new window).

Afterwards you can edit the documentation as you learned earlier.

PRO TIP

If you want to automate the process of automatically having your fork in sync , you may want to use pull bot (opens new window)

# Creating a pull request

The last step to aligning the changes that you have made with the original repository is to create a pull request (opens new window).

Navigate to your fork on github. For example https://github.com/YOUR_GITHUB_NAME/Xenial.Framework. Github will normally guide you through the process of creating a pull request once you have clicked on the Pull request link.

Clicking the Pull request link

Make sure your source branch and the target branch are correct. By default this should be main. If you are a more advanced git user, you could of course create a separate branch.

Creating the pull request and making sure branches are set correctly

Afterwards you need to create the pull request:

Create the pull request

← Installation →