3.1.1. Collaborative Tools.#

Belle II is an international collaboration of more than 1000 members from all over the world. Since we are so spread out communication tools are really important.

You are reading this page, so you have already registered as a member and obtained DESY credentials. These allow you to access private areas of the belle2.org website. Many (but not all) services are hosted at <something>.belle2.org or <something>.desy.de.

../../_images/Belle2CollaborationMap20200709.png

Fig. 3.1 The collaboration as of 2020-07-09.#

Important services for you#

Here is a curated list of the services and tools that we think are most useful right away (for newcomers) and that are needed in these lessons.

confluence.desy.de

Our “wiki”. Editable, linked pages that can be easily modified and updated. Used for many things from run planning to tracking progress through a physics analysis.

gitlab.desy.de

Our Git server. All code should go here, ideally under the Belle II “group”. It is a rule that your analysis code must be viewable to the rest of the collaboration. To make this less painful, you should get happy with Git and GitLab. This is also our bug reporting and work-tracking system. Used to report problems, request features, request MC samples, and track work.

software.belle2.org

The documentation for the Belle II software. You might occasionally hear people refer to this as “sphinx”.

questions.belle2.org

Our Q&A forum. Something like stack exchange if you’ve ever used that.

chat.belle2.org

For chatting with other collaborators who are awake in your timezone.

Tip

What a lot of different places where information could be. If only there was a way to search all places at once!

We’ve got you covered. Try search.belle2.org.

You should note that confluence is part of a suite of commercial tools, while GitLab and “sphinx” are industry-standard open-source tools. This means that there is non-Belle II-specific help on the internet.

Question

The software documentation is built using a tool called “sphinx”. Where is the project’s homepage?

Solution

It’s at www.sphinx-doc.org. There is also an English-language wikipedia page here.

Question

Where is the documentation for confluence and gitlab?

Question

What markup language does sphinx use?

Solution

reStructured text (more on this later).

That’s not all#

It’s not immediately relevant right now, but there are many other services. There is a full and complete list of all services on confluence.

Belle II Collaborative Services and Tools.

Tip

You should probably bookmark the Belle II Collaborative Services and Tools page.

Where do I go for help?#

With all of these tools, it might be hard to work out where to go to get help.

Hint

If you get stuck or have any questions during a StarterKit workshop or with the training lessons in the online book you don’t need to think about where to ask: The #starterkit-workshop channel in our chat will provide fast help. Please also check out the quick tips section below: Asking a question in #starterkit-workshop.

… meta#

What if there is a problem with one of the collaborative tools themselves? It doesn’t happen often, but sometimes the web services go down. Or maybe you have trouble logging in. Then you should check the confluence page for the responsible person and/or email to b2-helpdesk@belle2.org.

… with my analysis#

Let’s assume you are working on an analysis when…

  • …you have an error message or something is happening with your analysis that you don’t understand. You should first try to understand it yourself.

    • Search for your error in the documentation, the source code, and in previous question posts.

    • If you don’t have any luck ask a question.

  • …something goes really wrong. You have a crash or a segmentation fault, or the output cannot possibly be correct. You probably have a bug. Bugs should be reported at https://gitlab.desy.de/belle2/software/basf2/-/issues. You should continue to try and investigate and understand it yourself.

… with the grid#

Let’s assume you are working with the grid when…

  • …you have an error message or something is happening that you don’t understand. You should first try to understand it yourself.

Some tips#

Asking a question in #starterkit-workshop#

Note

The #starterkit-workshop channel is for beginner’s questions about the online book material and for everything that happens during a StarterKit workshop. It’s not the right place for specific or very detailed questions about your own analysis.

Our chat works like any other chat with a couple of nice features. For example you can put small parts of code in backticks `print("hello world")` and you can add larger bits of source code in triple backticks like so (note that you can create a new line by pressing Shift-Enter):

```
print("foo")
print("bar")
```

The only thing that we would like you to pay attention to, is that you make use of the “threading” feature of our chat. This makes it easier to get an overview over all recent questions.

If you want to reply to an existing message, please click on the small icon on the right:

Clicking the reply button

If there are already several replies, you can also click the reply button below (it will open a side panel with all the replies):

Clicking the reply button

Exercise

Join the #test channel and type some quick test messages. Try to include some bits of “code” as shown above.

Exercise

Try out the “reply” feature, either by replying to one of the previous messages from other users or by replying to your own message.

Confluence#

Confluence is useful for easy documentation. We use it for glossaries, instructions, and planning. You will find: physics meetings discussion, the data-taking, data-reconstruction status, and much more on there.

It’s not reliable for software documentation.

Exercise

All Belle II data and simulation is centrally processed and reconstructed. This is handled by the “data-production group”. Find the current data-production status. What data is processed? What is on-going?

Solution

It’s on confluence: Data Production Status

Exercise

Find the run plan for the next (or current) data-taking period.

Solution

It’s on confluence: Run Plan

Question

There are some Belle II-specific acronyms and jargon that you will encounter in these lessons. What do the following mean?

  • FEI

  • ROE

  • BCS

Hint

There is a glossary. You should be able to find it.

Solution

Take a look at the Main Glossary on confluence.

There are some downsides to confluence. Pages may be outdated (check the “last edited” message at the top) and sometimes links are broken or pages re-organised.

If you think something is outdated you can leave a comment on the page, and the original author of the page will probably get back to you. If you are quite sure that something is outdated: please update it! You can always leave a comment asking experts to check your edit.

We try to avoid documenting software on confluence because software changes between versions. Pages can be simultaneously outdated and not outdated depending on the version of the software you are using.

Exercise

There is a sandbox confluence page for you to experiment with adding material. Go to the Confluence Training Test Page and add some content.

Some inspiration:

  • Link to a GitLab issue.

  • Link to another confluence page.

  • Tag your colleagues.

  • Add the date.

  • Add your favourite picture of a cat / piece of art.

How to ask a good question on questions.belle2#

Like most Q&A forums, questions.belle2.org is only as good as the posts. Even though you have a problem and you want help quickly it is worthwhile to take time on presentation.

  1. Search for existing questions.

  2. Try to boil down the issue to the minimal (non)-working example, what you expect to happen, as well as instructions on how to run it.

  3. Try to include all details that are needed to reproduce the issue but avoid walls of text.

  4. Include full error messages and logs.

  5. Make use of formatting (for code, logs, … ).

  6. If you use data, include a path or a small example data file.

  7. Choose an appropriate title, and use tags.

Question

What is an MWE?

Hint

This is jargon but it is not specific to Belle II.

Solution

It stands for minimal working example.

See also

There is a meta-question post: How do I ask a good software question here?

A bit more about formatting#

When writing your questions post, you can turn on “preview” (this is helpful). You can use simple markdown syntax. Code is indented by four spaces, and you can use latex!

This is some normal text.
This is normal text with inline code `[ x*x for x in range(10) ]`.

    # this is code (or a log message), indented 4 spaces
    for i in range(1000):
        print(i)

Here is something someone said as a quote:

> Ask good questions.

Here is some text with inline math: $ e^{-i\pi} = -1 $. Display math also works:

$$ \hat{f}(\xi) = \int_{-\infty}^{\infty} f(x)\ e^{-2\pi i x \xi}{\rm d}x $$

This gets rendered something like:

An example questions post.

Housekeeping#

When your question has been answered, you should mark it as “resolved” and up- (or down-) vote anything that was useful (or unhelpful).

You should also vote on other good questions. This helps everyone find relevant good information.

Click on the circle to choose an answer.

Fig. 3.2 Click on the circle with a check-mark to choose an answer. Click on the arrow to up-vote.#

Don’t forget to answer!#

The forum is a Q& A forum. If you know an answer to a question: answer it!

Tip

If you don’t know the answer, but know someone who you think might: please tag them in a comment.

A bit more about working with GitLab#

Exercise

Go to https://gitlab.desy.de

  • What’s displayed at the dashboard/home screen?

  • Find the main Belle II basf2 repository.

  • Look at the commits.

Solution

Some of that is just browsing. We trust that you did it. The main software repository is: https://gitlab.desy.de/belle2/software/basf2 , and the list of commits is here.

Here is a rough workflow for working with GitLab.

  1. Identify an issue: Feature requests, bug report, …

    • If you don’t know if it’s a real bug, you can always ask on questions.

  2. Open an issue on GitLab and assign someone to work on it

    • Click “create” and fill out the form.

    • It can be reassigned, so guess someone. Please choose an appropriate label for the issue (select one or more labels among the existing ones).

  3. Discuss there in comments: Is this really a bug? Do we really need this feature?

  4. You (or someone else will) create a branch that references the issue, write some code, and add some commits to the branch.

  5. You (or someone else will) open a merge request, add a reviewer, and add a clear description.

    • You (or someone else) can edit the text, title, and the reviewer after a first attempt.

  6. The reviewer looks at the changes, leave comments on code and in general.

  7. The developer will react to the reviewer

    • more commits to this branch

  8. After the review is done: write a comment with written “Merge” in the merge request!

Tip

You should already be ok with 1-3. With a bit of practice, and the Software Prerequisites, we hope you will be able to also do 4-8.

There is a problem with the documentation!#

As we mentioned before, the software documentation is generated by a tool called sphinx. This is nice because it is well integrated with python. The page you are now reading is written in sphinx.

Exercise

Find the source file for this page.

Hint

Scroll to the top and you should see a helpful looking link.

Solution

It’s here.

If you discover an omission or a problem (or even a typo) you can actually fix it quite easily yourself. It is a good excuse for a first merge request, and you will make the software developers very happy.

And finally: Be bold!#

You can make a difference!

People are nice: don’t be too afraid to bother them or break stuff (chances are you won’t, anyway). Ask for help on questions.belle2.org or leave a comment on a confluence page or on a GitLab issue.

Help us out with documentation: as a beginner, you know best what is missing!

Key points

Tip

Good questions are also documentation and are also helpful!

Tip

Bugs do exist, don’t hesitate too much to report them.

Stuck? We can help!

If you get stuck or have any questions to the online book material, the #starterkit-workshop channel in our chat is full of nice people who will provide fast help.

Refer to Collaborative Tools. for other places to get help if you have specific or detailed questions about your own analysis.

Improving things!

If you know how to do it, we recommend you to report bugs and other requests with GitLab. Make sure to use the documentation-training label of the basf2 project.

If you just want to give very quick feedback, use the last box “Quick feedback”.

Please make sure to be as precise as possible to make it easier for us to fix things! So for example:

  • typos (where?)

  • missing bits of information (what?)

  • bugs (what did you do? what goes wrong?)

  • too hard exercises (which one?)

  • etc.

If you are familiar with git and want to create your first pull request for the software, take a look at How to contribute. We’d be happy to have you on the team!

Quick feedback!

Author(s) of this lesson

Kilian Lieret, Sam Cunliffe