Add link descriptions and update wording

[svx]

What does this PR do?

This PR enhances the documentation about "contributing to the documentation" by:

• Adding link descriptions
• Update wording
• Add Docker as requirement if the user wants to use Docker to build the documentation locally

Motivation

This tiny change improves the docs for people who use screen readers (accessibility) and it explains that the user has to have Docker installed to use this method.
Some less experienced people, or people who are new, may not know that.

More

• Added/updated tests
• Added/updated documentation

Additional Notes

[nmengin]

Hey @svx,

Thank you for this contribution.
Could you rebase your PR on branch v2.9, please?

[svx]

@nmengin Should I close this one and create a new PR for the v2.9 branch?

[ldez]

Should I close this one and create a new PR for the v2.9 branch?

No, you just have to rebase your branch.

git rebase --onto=upstream/v2.9 HEAD^

If you need help ping me.

[svx]

@ldez ping!

I know how to rebase from a branch, but my PR is coming from a fork 😄

[ldez]

I will expect that you have the following state locally:

$ git remote -v                         
origin  git@github.com:svx/traefik.git (fetch)
origin  git@github.com:svx/traefik.git (push)
upstream        git@github.com:traefik/traefik.git (fetch)
upstream        git@github.com:traefik/traefik.git (push)

Then you have to run the following command:

git rebase --onto=upstream/v2.9 HEAD^

Otherwise, when you create a PR, I recommend using a dedicated branch instead of master or v2.9.

If you still have a problem, I can do it for you.

[svx]

@ldez Yeah, a branch would have been better, I will do that next time!

OK, so I have now

git remote -v
origin	git@github.com:svx/traefik.git (fetch)
origin	git@github.com:svx/traefik.git (push)
upstream	git@github.com:traefik/traefik (fetch)
upstream	git@github.com:traefik/traefik (push)

When I try git rebase --onto=upstream/v2.9 HEAD^

I am getting fatal: Does not point to a valid commit 'upstream/v2.9'

Sorry for the mess and extra time/work, I should know better.

[ldez]

I am getting fatal: Does not point to a valid commit 'upstream/v2.9'

I think you have to fetch the remote:

git fetch upstream

[svx]

@ldez I am closing this PR.
I feel not really comfortable with what I am doing here, rebasing forks with branches, etc.
Once I figured out how and to which branches PRs should be done according to good practices for Traefik, I will create a new one.
Thank you for all your help and patience !

[ldez]

You can leave your PR open, I can fix that.

It's more complex to fix than creating a PR on the right base, so it's not a problem if you don't feel comfortable with that.

[ldez]

FYI, you are not trying to "rebase forks with branches", you are just trying to rebase a branch from another branch.
A fork, as a git repository, cannot be rebased.

The --onto flag is just a way to cherry-pick a commit from your current branch to another one and update your branch to point to this new cherry-picked commit.

[svx]

@ldez Ok, thanks for the explanation!
I reopened the PR.

[ldez]

Thank you 👍

[nmengin]

LGTM 📖

[kevinpollet]

Thanks 👍

[svx]

Quick last question, sorry for being off-topic.
I can also ask in the community forum, but it is a bit related.

What are the best practices for PRs, I was not able to find that in detailed in the docs and would love to add it.

In a nutshell:

• Create fork (make sure to get all branches, on default GH, only forks main/master)
• Create a new (feature) branch in your fork
• Create PR from your feature branch against the latest (currently 2.9) in this repo ?

[ldez]

In fact, creating a dedicated branch is a generic best practice, not specific to Traefik.

Create fork (make sure to get all branches, on default GH, only forks main/master)
Create PR from your feature branch against the latest (currently 2.9) in this repo ?

The branch depends on the content of the PR, everything is explained inside the pull request description template (take a look at the description content of your own PR).
So you don't need to get all the branches, you just need to know the targeted branch.

FYI, in the past, a fork would get all branches, but recently GitHub changed that to only clone the main/default branch.

[svx]

@ldez Ok, great! Thank you!