From d26b75ea944868e4fcac72456fce9d2aa6b1d042 Mon Sep 17 00:00:00 2001 From: Martin Schroschk <martin.schroschk@tu-dresden.de> Date: Wed, 9 Jun 2021 08:55:01 +0200 Subject: [PATCH] WIP: git workflow --- doc.zih.tu-dresden.de/CONTRIBUTE.md | 65 ++++++++++++++++------------- 1 file changed, 35 insertions(+), 30 deletions(-) diff --git a/doc.zih.tu-dresden.de/CONTRIBUTE.md b/doc.zih.tu-dresden.de/CONTRIBUTE.md index 7e0e9fe73..da5102208 100644 --- a/doc.zih.tu-dresden.de/CONTRIBUTE.md +++ b/doc.zih.tu-dresden.de/CONTRIBUTE.md @@ -22,8 +22,9 @@ ZIH-related staff, please refer to [CONTRIBUTE_ZIH.md](Todo) for documentation. ## Contribute via Issue Users can contribute to the documentation via the [issue tracking system](https://gitlab.hrz.tu-chemnitz.de/zih/hpc-compendium/hpc-compendium/-/issues). -Open an issue to report typos and missing documentation or request for more precise wording etc. -ZIH staff will get in touch with you to resolve the issue and improve the documentation. +For that, open an issue to report typos and missing documentation or request for more precise +wording etc. ZIH staff will get in touch with you to resolve the issue and improve the +documentation. **Reminder:** Non-documentation issues and requests need to be send as ticket to [hpcsupport@zih.tu-dresden.de](mailto:hpcsupport@zih.tu-dresden.de). @@ -83,8 +84,6 @@ refer to the corresponding documentation for further information. ## Contribute via Local Clone -We highly recommend running the checks before committing and posing a merge request. - ### mkdocs Rocks As mentioned, this documentation bases on markdown files which are translated into static html files @@ -98,7 +97,6 @@ In principle, `mkdocs` is not mandatory on the local system to contribute to the also provides a builtin development server that allows to serve the documentation, i.e. it can preview the updated documentation locally before committing the changes to the repository. - To make use of `mkdocs`, it is necessary to have two commands in mind ``` mkdocs serve - Start the live-reloading docs server. @@ -139,41 +137,44 @@ INFO - Building documentation to directory: /PATH/to/hpc-compendium.git/doc. INFO - Documentation built in 0.09 seconds ``` -## Git Workflow +### Git Workflow -It is crucial to keep your branch synchronized with the upstream when you are working locally on the -documentation. -First thing you should do, is adding a remote pointing to the official documentation. +It is crucial to keep your branch synchronized with the upstream repository when you are working +locally on the documentation. At first, you should add a remote pointing to the official +documentation. ```Shell Session -git remote add upstream git@gitlab.hrz.tu-chemnitz.de:zih/hpc-compendium/hpc-compendium.git +git remote add upstream-zih git@gitlab.hrz.tu-chemnitz.de:zih/hpc-compendium/hpc-compendium.git ``` +Now, you have two remotes, namely *origin* and *upstream-zih*. The remote *origin* points to your fork, +whereas *upstream-zih* points to the original documentation repository at GitLab Chemnitz. +```Shell Session +$ git remote -v +origin git@gitlab.hrz.tu-chemnitz.de:LOGIN/hpc-compendium.git (fetch) +origin git@gitlab.hrz.tu-chemnitz.de:LOGIN/hpc-compendium.git (push) +upstream-zih git@gitlab.hrz.tu-chemnitz.de:zih/hpc-compendium/hpc-compendium.git (fetch) +upstream-zih git@gitlab.hrz.tu-chemnitz.de:zih/hpc-compendium/hpc-compendium.git (push) +``` +Next, you should synchronize your `main` branch with the upstream. -<!--You should see two remote endpoints, origin points to your fork and upstream at main repo.--> - -<!--$ git remote -v--> -<!--origin git@gitlab.com:<username>/nersc.gitlab.io.git (fetch)--> -<!--origin git@gitlab.com:<username>/nersc.gitlab.io.git (push)--> -<!--upstream git@gitlab.com:NERSC/nersc.gitlab.io.git (fetch)--> -<!--upstream git@gitlab.com:NERSC/nersc.gitlab.io.git (push)--> - - <!--Checkout main and sync main branch locally from upstream endpoint--> +```Shell Session +git checkout main +git pull upstream main +``` -<!--git checkout main--> -<!--git pull upstream main--> +At this point, your `main` branch is up-to-date with the original documentation of HPC compendium. <!--To push your sync changes to your fork you can do the following:--> - <!--git push origin main--> - #### Making Changes and Merge Requests -The main branch is used to synchronize changes from upstream. It should not be used for changes. -In order to commit to this documentation, create a new branch (a so-called feature branch) basing on the main branch and commit your changes to it: +It is good git-practise to only use the `main` branch for synchronization with the upstream, not for +changes, as outlined in the previous subsection. In order to commit to this documentation, create a +new branch (a so-called feature branch) basing on the `main` branch and commit your changes to it. ```Shell Session git checkout main @@ -184,13 +185,17 @@ git commit -m <COMMIT MESSAGE> git push origin <FEATUREBRANCH> ``` -Having your changes pushed to your fork, create a merge request to the main branch. +The last command pushes the changes to your remote at branch `FEATUREBRANCH`. Now, it is time to +incoporate the changes and improvements into the HPC Compendium. For this, create a +[merge request](https://gitlab.hrz.tu-chemnitz.de/zih/hpc-compendium/hpc-compendium/-/merge_requests/new) +to the `main` branch. -<!--Please make sure the markdownlint check and continuous integration checks have passed for your merge request.--> +#### Run Checks -<!--* It is possible the GitLab shared runners will fail for an opaque--> - <!--reason (e.g. issues with the cloud provider where they are hosted).--> - <!--Hitting the **Retry** button may resolve this problem.--> +We have several checks on the markdown sources to ensure a high quality of the documentation. These +checks are run within the CI/CD pipeline and changes are only deployed to the HPC compendium, if the +checks are passed. +Thus, we **highly recommend** running the checks before committing and posing a merge request. -- GitLab