Collaborative Tools.
Contents
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.
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?
Solution
At support.atlassian.com/confluence-cloud and docs.gitlab.com!
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.
Look at recent announcements on the comp-users-forum mailing list.
Look for question posts on a similar topic.
If you don’t have any luck ask a question or send an email to comp-users-forum@belle2.org.
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:
If there are already several replies, you can also click the reply button below (it will open a side panel with all the replies):
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.
Changing your name in our chat#
It’s important that you set your name in the chat to your real name (first and last name). Not only does this make it easier for other people to find you, it’s also the only way for other people to tag you directly in a chat. This does not even work if people use “@yourusername” if your actual name isn’t stored in the chat system. To add your name, perform the following steps:
Login to the chat
Click on your avatar / profile picture in the top left corner
Click on “My Account”
Go to “Profile”
Fill your name in the “Name” field, which is next to the field with your “Username”
Click “Save changes” in the top right corner
You follow the same steps if you want to change your name later on, but please be aware that this might again cause some confusion, so please use your given name (first and last name) right from the beginning.
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.
Search for existing questions.
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.
Try to include all details that are needed to reproduce the issue but avoid walls of text.
Include full error messages and logs.
Make use of formatting (for code, logs, … ).
If you use data, include a path or a small example data file.
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:
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.
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.
Identify an issue: Feature requests, bug report, …
If you don’t know if it’s a real bug, you can always ask on questions.
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).
Discuss there in comments: Is this really a bug? Do we really need this feature?
You (or someone else will) create a branch that references the issue, write some code, and add some commits to the branch.
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.
The reviewer looks at the changes, leave comments on code and in general.
The developer will react to the reviewer
more commits to this branch
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.
See also
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
Software documentation → software.belle2.org.
Ask questions (and answer them) at questions.belle2.org.
Confluence is our wiki.
Code, bugs, feature requests → gitlab.desy.de.
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 merge 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