.. _onlinebook_collaborative_tools: Collaborative Tools. ==================== .. sidebar:: Overview :class: overview **Length**: 15-30 minutes **Prerequisites**: * DESY accounts. * An internet browser. **Questions**: * Where do I find information? * Where can I ask for help? * Where can I report bugs? * Where do I find the source code? **Objectives**: * Learn where things are or where to look. * Learn to ask good questions at the right places. * Learn how to report problems. 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 probably `registered as a Belle II 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 **.belle2.org** or **.desy.de**. .. figure:: collaborative_tools/Belle2CollaborationMap20200709.png 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. `xwiki.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 `_. **GitLab** and **"sphinx"** are industry-standard open-source tools. This means that there is non-Belle II-specific help on the internet. .. admonition:: Question :class: exercise stacked The software documentation is built using a tool called "sphinx". Where is the project's homepage? .. admonition:: Solution :class: dropdown solution It's at `www.sphinx-doc.org `_. There is also an English-language wikipedia page `here `__. .. admonition:: Question :class: exercise stacked Where is the documentation for **XWiki** and **gitlab**? .. admonition:: Solution :class: dropdown solution At `xwiki.org/xwiki/bin/view/Documentation `_ and `docs.gitlab.com `_! .. admonition:: Question :class: exercise stacked What markup language does sphinx use? .. admonition:: Solution :class: dropdown 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 XWiki. .. centered:: `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: :ref:`onlinebook_collaborative_tools_b2chat_howto`. ... 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 XWiki 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 ``_. 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 --------- .. _onlinebook_collaborative_tools_b2chat_howto: 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): .. code-block:: ``` 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: .. figure:: collaborative_tools/reply_1.png :align: center :alt: 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): .. figure:: collaborative_tools/reply_2.png :align: center :alt: Clicking the reply button .. admonition:: Exercise :class: exercise Join the `#test channel `_ and type some quick test messages. Try to include some bits of "code" as shown above. .. admonition:: Exercise :class: 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: 1. Login to `the chat `_ 2. Click on your avatar / profile picture in the top left corner 3. Click on "My Account" 4. Go to "Profile" 5. Fill your name in the "Name" field, which is next to the field with your "Username" 6. 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. XWiki ~~~~~ XWiki 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. .. admonition:: Exercise :class: exercise stacked 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? .. admonition:: Solution :class: dropdown solution It's on XWiki: `Data Production Status `_ .. admonition:: Exercise :class: exercise stacked Find the run plan for the next (or current) data-taking period. .. admonition:: Solution :class: dropdown solution It's on XWiki: `Run Plan `_ .. admonition:: Question :class: exercise stacked There are some Belle II-specific acronyms and jargon that you will encounter in these lessons. What do the following mean? * FEI * ROE * BCS .. admonition:: Hint :class: dropdown xhint stacked There is a glossary. You should be able to find it. .. admonition:: Solution :class: dropdown solution Take a look at the `Main Glossary `_ on XWiki. There are some downsides to XWiki. 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 XWiki because software changes between versions. Pages can be simultaneously outdated and not outdated depending on the version of the software you are using. .. admonition:: Exercise :class: exercise There is a sandbox XWiki page for you to experiment with adding material. Go to the `XWiki Training Test Page `_ and add some content. Some inspiration: * Link to a GitLab issue. * Link to another XWiki 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. 0. Search for existing questions. 1. 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. 2. Try to include all details that are needed to reproduce the issue but avoid walls of text. 3. Include full error messages and logs. 4. Make use of formatting (for code, logs, . . . ). 5. If you use data, include a path or a small example data file. 6. Choose an appropriate title, and use tags. .. admonition:: Question :class: exercise stacked What is an MWE? .. admonition:: Hint :class: dropdown xhint stacked This is jargon but it is not specific to Belle II. .. admonition:: Solution :class: dropdown solution It stands for minimal working example. .. seealso:: `This excellent stack overflow post `_ and `this English language wikipedia page `_. .. seealso:: 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! .. code-block:: 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: .. figure:: collaborative_tools/formatting.png :width: 750px :align: center :alt: 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. .. figure:: collaborative_tools/close_and_upvote.png :width: 150px :align: center :alt: Click on the circle to choose an answer. 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. admonition:: Exercise :class: exercise stacked 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. .. admonition:: Solution :class: dropdown 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 :ref:`onlinebook_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. .. admonition:: Exercise :class: exercise stacked Find the source file for this page. .. admonition:: Hint :class: dropdown xhint stacked Scroll to the top and you should see a helpful looking link. .. admonition:: Solution :class: dropdown solution It's `here <../../_sources/online_book/welcome/collaborative_tools.rst.txt>`__. 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. .. seealso:: :ref:`doctools` .. seealso:: `How do I make a merge request? `_ (previously called pull request) 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 XWiki page or on a GitLab issue. Help us out with documentation: as a beginner, you know best what is missing! .. admonition:: Key points :class: key-points * Software documentation → `software.belle2.org `_. * Ask questions (and answer them) at `questions.belle2.org `_. * `XWiki `_ 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. .. include:: ../lesson_footer.rstinclude .. rubric:: Author(s) of this lesson Kilian Lieret, Sam Cunliffe