Communication Guidelines for RST

The SuperDARN Data Analysis Working Group (DAWG) is a collaborative group of developers, scientists, and engineers that focus on developing software to analyze the SuperDARN data from raw data (RAWACF, and sometimes IQDAT) to secondary data (FITACF, GRID, MAP, … etc). This document is set up to help new and current developers in the Data Analysis Working Group (DAWG) that work on the RST repository (and possibly other repos in the future) communicate issues, problems, pull request reviews and solutions in a constructive and professional manner. For some members of the DAWG, this method for collaborative code development may be completely new. These guidelines are not strict rules and can be reviewed later on if problems arise in a constructive, collaborative manner.

Some of these guidelines were inspired by the great piece from Alex Hill’s “The Art of Giving and Receiving Code Reviews”.

The following communication methods this document will address is:

• GitHub Issues
• GitHub Pull Requests Reviews

General

• While most of us work with SuperDARN research groups, there is a mix of space scientists, engineers and programmers with varying lengths of experience in the SuperDARN field as well as their profession. This can create different approaches to the same problem.
• Comments and reviews that reflect more on coding style and not coding function or content should be avoided. The WG and the RST repo have not adopted a coding style guide, so it is difficult to expect code to look a certain way.
• Remember that DAWG members operate in different time zones and have priorities outside of the DAWG. Allow enough time for others to provide feedback and for the discussion to take its course before merging.

Giving feedback

• Avoid personal direct comments: Recognize that we are all working to improve SuperDARN’s data products and processing. In this collaborative environment, remember to think of it as a group and not the individual (although it can be helpful to ask for an individual’s opinion as they may be more familiar with certain parts of the repo).
• Respect the developer: writing and code are usually taken personally as it requires a lot of time. Saying thank you, and focusing on constructive comments goes a long way. It is easy as a reviewer to make a sharp or negative comment, however, it may be more damaging to the developer/writer. If this happens, make sure to say sorry as well - acknowledging your mistake, misunderstanding or attitude defuses the negativity and helps with refocusing on the situation at hand.
• Proofread comments: After writing a comment or code review, read over what has been written and think of ways it could be taken negatively or misinterpreted.
• Avoid scope creep: Keep comments and feedback relevant to the current issue or pull request. If you think of a related topic, feel free to open up a new issue and link it back to the original conversation.
• Be concise: Try to keep the number of points or questions in any one bit of feedback limited to just a few to help prevent the discussion from splitting into many directions and to help others reading your feedback to digest your points. Delaying or postponing points or topics can be frustrating as you do not want to forget them later on.
• Summarize: If necessary to have more than a few points, try to summarize them into bullets or a checklist and expand on them one/few at a time, waiting for one/some to be resolved before moving on.
• KIS: Keep it simple! Remember that anything on GitHub or said in a meeting is public. If a debate or larger discussion is needed, it should be addressed during a teleconference to avoid ballooning of the GitHub issue/pull request.
• Comment on good days: to avoid negative comments, it is advised to review and comment when you are in a better state of mind.

Receiving feedback

• Say 'thank you': It is hard sometimes, but remember the reviewer took time out of their schedule to review your code. As with giving feedback, remember that we are all volunteers since the RST code is an open source package. Since a person has taken their time to provide feedback, try to be thankful for the effort and time they have put into the reading and/or review that’s needed to provide this feedback.
• Be mindful of the reviewer: When receiving a code review or feedback on a comment or issue, take into account the perspective of the reviewer as well as the possibility that the person was having a bad day.
• Don’t take things personally: Remember a code review or feedback is not a reflection on you personally but part of the process of working collaboratively. If you are feeling attacked, take a break from it. Review it again later.
• Set boundaries: If a reviewer is being negative and not constructive/professional, please address it to the DAWG chairs. Don’t be afraid to let others know you are uncomfortable with certain behaviors or comments. If there are many comments and it seems overwhelming to you, you can ask for the reviewer to try and reduce the comments and give suggestions. Another idea is to separate the work into smaller chunks.

---

Other thoughts for another document (leaving them here to retain these ideas)

For other information on the workflow/development in RST please reference (currently in the work, guidelines have not been written yet):

• Pull Request and Issues guidelines
• Code style guidelines
• Release guidelines
• Workflow and branching guidelines If guidelines are not available yet and unsure about something, please make sure to ask the community of the DAWG chairs for guidance. This may help them include your questions or concerns in the guidelines.