Definition 2.4.1.
A repository, aka repo, is a file storage location used by a version control system to keep track of not only versions of the code base itself, but also to keep track of project documentation, discussions, web pages, and more.
Section 2.4 OSS Community Communication
Communication in an open-source community takes many forms, but all of these break down into two broad categories: synchronous (simultaneous, e.g. in-person meetings or video conference meetings) and asynchronous (non-simultaneous, e.g. email or various kinds of messaging services). Due to the geographically-dispersed nature of most communities, most OSS communication makes heavy use of asynchronous technologies. Synchronous communications typically include various forms of audio/video chat, which is neither convenient nor efficient for widely dispersed OSS communities. Asynchronous communications are much more varied and most OSS communities use more than one asynchronous form of communication. When a software team is made of full-time people who all work the same hours in the same office building, it is easier to have a higher proportion of synchronous discussion, but when some contributors are sleeping while others are working, it is far harder, so it is not a big surprise that the vast majority of OSS communication is asynchronous.
Subsection 2.4.1 Website
The first place where people discover an OSS community is typically a website. To make a website available to all users, it must be hosted on a web server referred to as a host that serves the page. Unfortunately, the nature of traditional HTML pages is that they are often a static, one-to-many form of communication created by a small number of people with write access to the server. This leads to websites that can become quickly outdated and which do not truly reflect the collaborative nature of the community. We will see how OSS communities work around this issue and make their website a collaborative project in the next section.
All OSS communities need to have their code hosted in a place where it can be viewed and potentially contributed to. This is where software engineering collaboration platforms step in.
Subsection 2.4.2 Software Engineering Collaboration Platforms (SECP)
Virtually every open source community uses a Software Engineering Collaboration Platform (SECP) such as GitHub, Gitea, GitLab, or Bitbucket, each of which provides a comprehensive collection of features that are required for software development in OSS communities. These features arise naturally from the need to store code, to discuss issues related to the code, to employ version control, and other needs:
1
github.com/2
gitea.io3
gitlab.com/4
bitbucket.orgSubsubsection 2.4.2.1 Repository
It goes without saying that an OSS needs to store the code base in a way that it can be accessed by the community of current and potential contributors. Repos are nearly always hosted in a SECP, although they are also sometimes self-hosted by the project.
Subsubsection 2.4.2.2 Issue Tracker
Definition 2.4.2.
An issue typically refers to any problem, request, question, or other task that is tracked and managed within the project’s issue-tracking system.
Definition 2.4.3.
An issue tracker is a tool used by software development teams to record, track, prioritize, and resolve issues such as bugs, feature requests, other suggestions and problems reported by users, etc.
After an issue is posted, discussions on the issue typically occur and are sometimes prolonged. These discussions are most conveniently attached to the issue itself to facilitate the tracking of the discussion, which is particularly important in larger projects. When an issue is posted, it can be discussed by the community to decide on how to proceed with it. The issue can be categorized and linked to other discussions, projects, and engineering work as well. You are definitely advised to read or search through all unresolved issues before posting so you are not duplicating an existing issue.
A number of features exist in most issue trackers that facilitate communication among contributors and potential contributors. These include linking, labelling, mentioning a particular user, etc.
One important feature that exists in issue trackers is the ability to label the issue with one or more of a set of labels. GitHub, for example, provides the following default labels:
-
bug: indicates an unexpected problem or unintended behavior.
-
documentation: indicates a need for improvements or additions to documentation.
-
duplicate: indicates similar issues, pull requests, or discussions. These related items are then typically linked for convenience.
-
enhancement: indicates new feature requests.
-
good first issue: indicates a good issue for first-time contributors. The mere presence of this label indicates an openness to new contributors, so this is a very important label to look for when you are a potential new contributor.
-
help wanted: indicates that a maintainer wants help on an issue or pull request.
-
invalid: indicates that an issue, pull request, or discussion is no longer relevant.
-
question: indicates that an issue, pull request, or discussion needs more information.
-
wontfix: indicates that work won’t continue on an issue, pull request, or discussion.
Note that although the above default labels are included in every new GitHub repository, maintainers may or may not use all of them, and many maintainers choose to edit or delete some of the default labels and/or add their own custom labels that make sense for the project they maintain.
Subsubsection 2.4.2.3 Merge Request
Definition 2.4.4.
The term merge request (MR) or pull request (PR) describes a request to initiate the process of integrating specific code changes into the project repository.
Best practice before making a merge request is to have initiated an earlier discussion using one of the forms of communication favored by the project. After this discussion, a (potential) contributor opens a merge request, which may then undergo several iterations of automatic checks, manual code reviews by one or more other contributors, as well as further discussion.
It is important to understand that even in the best of circumstances, the typical merge request initiates further discussion and/or recommendation(s) for improvements from the core team of the OSS project. To those new to the OSS world, these discussions may come as a surprise, but they should not. Even then the core OSS team is likely to ask for further refinements. This is normal and to be expected.
Subsubsection 2.4.2.4 Project Board
Definition 2.4.5.
A project board is a tool that facilitates organization of project tasks.
Project boards typically utilize a visual tool similar to the Kanban scheduling system used in lean manufacturing. SECPs provide such boards, and many projects use the ones provided in their SECP. However, some projects use an external tool like Trello or one of the open source alternatives such as Kanboard or Taiga. These project boards are typically made up of things like issues, merge requests, files, tags, and notes that are categorized as cards which are organized into columns. Most platforms offer a lot of flexibility, so one can add tags, set deadlines, search, reorder columns, reorder cards within a column, move cards from one column to another column, etc. The project boards at: Microsoft VSCode Project Boards and Homebrew Project Boards, and NixOS Project Boards offer good examples of projects that use the SECP’s project boards.
5
en.wikipedia.org/wiki/Kanban6
trello.com7
kanboard.org8
taiga.io9
microsoft/vscode/projects?type=classic10
github.com/orgs/Homebrew/projects?type=classic11
github.com/NixOS/nixpkgs/projects?type=classicIf you wonder why some projects don’t seem to use project boards, consider that in many OSS projects, there are no paid project leaders who can set goals, organize all of the issues into boards, prioritize tasks, etc. For the majority of OSS projects, there either isn’t time to manage project boards or the project is too small to derive much benefit from their use.
One of the many features that software engineering collaboration platforms (SECP) sometimes offer is web hosting, which, when enabled, facilitates structured collaborative editing of the site. As an example, GitHub Pages affords hosting as a website for projects that are managed on GitHub. This means that OSS communities can use their SECP of choice as a host for their website as well.
12
pages.github.comSubsection 2.4.3 Other Asynchronous Communication Tools
Many other communication tools exist in OSS, but the following are some of the most prevalent:
-
Collaborative Instant Messaging Platforms.In recent times, collaborative instant messaging platforms like Discord, Matrix
13
discord.com, Mattermost14
matrix.org, Slack15
mattermost.com, and others have become very heavily leveraged in OSS communities. Each of these platforms has their own flavor, and the choice of which of these to use is largely driven by the OSS community. Discord was originally favored by gamers. Matrix is decentralized, open source, offers end-to-end encryption, and is the primary choice for some larger projects like Firefox16
slack.com. Mattermost is also open source and is most proud of being dedicated to security, so the Mattermost website highlights users like the US Department of Defense. Slack was developed for professional and organizational communications, and is also very heavily utilized by many OSS projects. Some commonalities across all of these collaborative instant messaging platforms is that communication is carried out in channels which individual users are placed in or choose to join. In addition to human users, various services and bots (programs providing automation) are present in many channels. Nicknames or handles are used, although in some OSS communities, the handles must adhere to the rules of the project (e.g. being identical to your handle on the project’s SECP).17
wiki.mozilla.org/Matrix -
Wiki.
Definition 2.4.6.
Simply stated, a wiki is a hypertext publication where the pages are a user-editable, easy-to-use, asynchronous way of putting semi-permanent content on the web.Although wikis can be created within many of the SECPs, the concept of a wiki is widely used and understood outside of SECPs as well, largely due to the wide popularity of Wikipediaand WikiMedia18
wikipedia.org. Wikis are useful for documentation, timelines, status reports, meeting minutes, and conversation logs. A wiki provides easy version control, a database backend, simplified markup, and a fast edit-and-post cycle. Having said this, the use of wikis for OSS projects have fallen largely out of favor in place of having markdown files in the code repository since markdown allows using the same tools such as merge requests, which has the additional benefit that changes to the documentation can be part of the merge request that introduces the relevant change.19
wikimedia.org -
IRC.
Definition 2.4.7.
Internet Relay Chat (IRC) is old-style text-based chat system for instant messaging and synchronous communication between people working on a OSS project.IRC is one of the older means of synchronous communication between people working on a OSS project, and although in the past it was one of the primary OSS communication tools, many projects have abandoned IRC for collaborative instant messaging platforms and other newer communication tools. It’s a text-based federated chat system where clients connect to the servers of one or more networks, and the servers relay messages between themselves within each network (hence the name). Communication is done in channels which individual users join, and users are identified by nicks (nicknames). In addition to human users, like collaborative instant messaging platforms, various services and bots are present in many channels. However, IRC is very lightweight because its focus is solely on the textual content, which means it can work right from your command line. However, there is no formatting, not even new lines, no emojis, no voice or video chat, and unlike most more modern chat technologies where recordings can be automated, messages aren’t easily stored, so it is designed to work only for synchronous communication. -
Blog.
Definition 2.4.8.
A blog, which is a truncation of weblog, is an informational website published on the World Wide Web consisting of individual, often informal entries called posts.A website provides semi-permanent places for content which is updated and replaced as needed. While in a blog, new articles that are published add to the content rather than replacing it (although existing posts can be updated as well if things change). Blogs provide a flow of transient, in-the-moment news, commentary, and technical articles which are posted by date, with past posts still available. Because many open source participants write blogs, it is sometimes difficult to keep up with them on a larger project. The volume of blog postings created within a community can be overwhelming. To help deal with this, RSS feeds enable the receipt of content in a machine-readable format so that it can be used in a variety of different ways through a service called a RSS feed aggregator. A few open-source communities also maintain a Planet site which aggregates the feeds from that community into a single page (and the Planet, in turn, provides an aggregated feed). Here are some examples: The Mozilla Planet, The Fedora Planet20
planet.mozilla.org, and The Document Foundation Planet21
planet.fedoraproject.org.22
https://planet.documentfoundation.org/As you get into OSS, you may want to share your news and opinions with others via a blog. Remember to represent your thoughts professionally, bearing in mind that the Internet is semi-permanent. If you don’t want a potential future employer to see what you write, don’t post it because the Internet Archiveand/or other crawlers may capture it forever.23
archive.org -
Mailing List.You likely know that an electronic mailing list is a collection of names and email addresses used to send material to multiple recipients, typically given a single email address for the list. Open source communities that use email lists tend to use discussion lists (which allow for replies) rather than announcement lists (which are one way) to engage their communities. An example of an open source project that leverages email lists heavily for discussions is Debian. Note that all emails sent to the Debian lists are distributed both to the list subscribers as well as copied to the public archive, so people to browse or search without the need to be subscribed.
24
www.debian.org/MailingListsPeople on an email list typically use their real name. Surprisingly, there is a significant variation from community to community in terms of list etiquette and even the amount of participation on lists.An open-source participant subscribed to several lists in multiple communities can easily receive thousands of messages a day. For this reason, many people choose to use a separate mailbox or use filtering rules to keep their mail under control or sign up to receive only a regular "digest" of the messages.Mailing lists are sometimes managed through online list service providers such as Google Groups, but are often managed through private installations of list management software such as the open source GNU Mailman, which provide subscriber management, bounce control, and web-accessible archiving.25
gnu.org/software/mailman/ -
Forum.A web-based forum has some similarities to an email list because users can subscribe to receive updates via email. However, conversations in forums are typically grouped by discussion topic and are often better-organized than email archives, which makes them easier to browse and search. People on a forum typically have handles or nicknames, rarely using their full real name, unlike in email. Many OSS communities have one or more forums specific to various aspects of the project. There are also forums that span multiple OSS communities. For example, It’s FOSS Communityis an example of an active forum on FOSS.
26
itsfoss.communityOther OSS communities use related communication technologies such as newsgroups and listservs which serve some of the same purposes as mailing lists and forums and often offer e-mail notifications as well.
Checkpoint 2.4.9. Exercise: Joining the Discussion.
Subscribe to at least one communication venue from each of the three open source communities you are observing, and read through the last few months of messages or message archives for each list. Blog your observations of their communication.
Subsection 2.4.4 Synchronous Communications
Although pretty much all OSS communities use asynchronous communication, there are some OSS communities that also leverage synchronous communication. Sometimes these sessions are for just a small set of core developers, but other times these are open to all. For example, both the open source textbook platform Runestone Academy and the open source authoring language PreText offer video drop in "office hours" open to users and contributors alike. However, as mentioned above, these are not going to be convenient from all regions of the globe, so both of these communities also utilize asynchronous communication methods. Runestone Academy uses Discord, while Pretext uses Google Groups for several very active mailing lists.
27
blog.runestone.academy/28
pretextbook.org/Drawing Conclusions.
We learn to read before we learn to write; in the same way, the best way to start working with an open source community is to observe that community in action. As you have completed the exercises in this chapter, you should have started to form an impression about the communities that you have been observing.
Checkpoint 2.4.10. Exercise: Share Your Thoughts.
Write a blog post summarizing your thoughts about the communities you’ve been observing. Specifically note your conclusions about the qualities of the community identified earlier.
Checkpoint 2.4.11.
Which of the following features are commonly provided by Software Engineering Collaboration Platforms (SECP) used in open-source communities?
- Document editing and file management
- This option is not specific to SECP features and does not encompass the functionalities mentioned in the section.
- Mailing list and forum integration
- While mailing lists and forum integration are mentioned in the text, they are not exclusive to SECP features.
- Repositories and merge requests
- Correct! Software Engineering Collaboration Platforms (SECP) typically provide features such as repositories for code storage and merge requests to initiate code integration.
- Collaborative instant messaging and wikis
- While collaborative instant messaging and wikis are mentioned in the text, they are not exclusive to SECP features.
You have attempted of activities on this page.
