SCS documentation

Links

The main repository for this documentation is here: https://git.xfel.eu/gitlab/SCS/documentation This is where you can both edit the documentation and preview how it looks like.

An all-shiny version of the documentation can be found on read-the-docs, here: https://rtd.xfel.eu/docs/scs-documentation/en/latest It should automagically show the newest version of the documentation, albeit with a delay of a minute or so.

From within the XFEL or DESY office network, there is another option: http://exflqr30526:8000/. That one actually should show all branches from gitlab.

Gitlab webpage workflow

You may change or add all files from right here. Just click on folders up there. In the folders you will find a file called index.rst, which contains the main description of the folder. Other rst files or folders may exist as well.

Once you click on the rst file, you see its contents. It’s just a preview, the real thing is mentioned in the section Links. You may click Edit to edit the file, http://docutils.sourceforge.net/docs/user/rst/quickref.html gives a short introduction what you can write in those files. Most of it should be self-explanatory.

Instead of editing a file, you may also Replace it, there is a button for that. That’s useful if you edited it in an external editor, especially when we are talking about graphics. You may also add new files, using the big + button above the folder structure.

Once you are done editing, you should add a Commit message below the edit field, to tell your fellow SCSers what in world you changed, and why. A short line should be fine. If you want to write more, write one short line with a really brief summary, leave one line empty, and then write as much details as you like.

Then you may give your changes a Target branch name. You are free to keep the one thats proposed by gitlab, but you may opt to put something else. It is only for your memory to find it again later, and will be forgotten later.

When you edit the documentation, usually the preview on gitlab is all you need. If, however, you are doing some advanced stuff and you want to see how the all shiny version looks like, call the branch that you edit “test”, and the shiny version will show up here: https://in.xfel.eu/readthedocs/docs/scs-documentation/en/test/

Start a new merge request if you want your changes to eventually become public, and commit the changes! You will be guided to a page where you can add other information, probably the only interesting one being that you can assign somebody else to look at what you did, but that’s just an option. Submit merge request is now the button to click.

Now somebody should look at your merge request, comment it, fix it, until it can be merged into the master branch.

Git command line workflow

0. Before anything, get a copy of the repository:

   git clone https://git.xfel.eu/gitlab/SCS/documentation.git
   

1. Before making any changes, let’s create a new branch to host these changes:

   git checkout -b new_branch_name
   

2. Then make appropriate changes, add, modify or remove file. Do test the change you make.

3. See what changed:

   git status
   

3. Adds the changes you want to save:

   git add filename_of_file_that_changed
   git add another_filename_of_file_that_changed
   

4. Once all relevant changes have been added, create a commit (bundle) of these changes:

   git commit -m 'Adds this and this changes'
   

5. Push the changes upstream:

   git push -f origin new_branch_name
   

   where new_branch_name is the name of the branch that was created in step 1.

6. Creating a pull request with the link given at the previous step