IEEE SA Open
Getting Started

Creating your IEEE SA OPEN Single Sign On

To sign in for the first time:

  • If you are an IEEE member, log in to your IEEE account and then visit https://opensource.ieee.org and use your existing IEEE credentials to log in.
  • If you are not an IEEE member, create a free account by visiting the Create an IEEE Account page. Fill in the appropriate information (making sure to preserve these credentials for later use). When you have succeeded in creating an IEEE account, you will be returned to the main IEEE page. You will now be able to access the IEEE SA OPEN site. Return to https://opensource.ieee.org.
create ieee sa open single sign on 1

Click in the inbox (highlighted in green in the above image) and you will be sent to the sign-in page (shown below). Use your IEEE login information to sign in.

create ieee sa open single sign on 2

The first time you log in, you will be asked to agree to the IEEE SA OPEN Terms of Use. Please scroll to the bottom of this page and click the green Accept terms button.

create ieee sa open single sign on 3

After you log in, you will be taken to the main page of IEEE SA OPEN. It runs on the popular GitLab CE platform. These same credentials will also allow you to log in the IEEE Mattermost chat server.

How to Sign a Contributor License Agreement

When you sign on to the IEEE SA OPEN platform, you are joining a community of contributors. To make sure that your contributions to our community are licensed appropriately, please sign a Contributor License Agreement. Our community shares our work through the Apache 2.0 license

If you need to sign a different license for a specific project, choose the Contributor License Agreement(CLA) that corresponds with the license for the project you are working on. (As of October of 2020, IEEE SA OPEN supports the following licenses: BSD 3-Clause, Apache 2.0, or CERN OHL 1.2.)

CLA

There are three versions of each Contributing License Agreement. Please choose the one that is appropriate to your situation. If you are signing on behalf of a company, please complete the entity CLA. If you are contributing as an individual, please choose the individual CLA. If you are adding something to the public domain as a representative of a government, please complete the option with the public domain declaration.

CLA

The first page of the CLA document provides instructions for how to choose a CLA document, how to fill it out, and how to submit it. Please email the signed CLA to oscontrib@ieee.org.

Once the CLA is signed and the submission process is completed, a CLA number will be provided to the representative or individual that submitted it.

Notifications In Gitlab

Setting up Notifications

Notifications allow you to stay informed about what's happening in GitLab. With notifications enabled, you can receive updates about activity in projects and groups. Notifications are sent via email.

Global notification settings

Your Global notification settings are the default settings unless you select different values for a project or a group.

gitlab notifications 1

Notification email
This is the email address your notifications will be sent to.

Global notification level
This is the default notification level which applies to all your notifications. Initially, this is set to the [Participate] option.

Notification scope

You can tune the scope of your notifications by selecting different notification levels for each project and group.

Notification scope is applied in order of precedence (highest to lowest):

Project
For each project, you can select a notification level. Your project setting overrides the group and global settings.

Group
For each group, you can select a notification level. Your group setting overrides your default setting.

Global (default)
Your global, or default, notification level applies if you have not selected a notification level for the project or group in which the activity occurred.

Project and Group Notifications

As noted above, you can select a notification level and email address for each project or group.

To select a notification level for a project or group, use either of these methods:

  • Click on your profile picture and select Settings.
  • Click Notifications (highlighted green in the picture below) in the left sidebar.
  • Locate a group or subgroup in the Groups section of the Notifications page to change its setting. A project may be found in the Projects section below the Groups section. If you would like to specify notification levels for individual projects in one group, you will need to visit that project's page and change the level there.
  • Select the desired notification level.
  • For groups only, you can also select an email address from the dropdown menu beside the notification level . This could be useful if you would like to separate email about different groups. This option is not available at the project level. Email addresses can be added to your account by clicking on the Emails option (highlighted pink in the picture below) and following the instructions there.
gitlab notifications 2

OR

  • Alternately, you may change your notification settings by navigating to the group's or project's page.
  • Click the notification dropdown, marked with a bell icon (highlighted in green below).
  • Select the desired notification level.
gitlab notifications 3

Notification Level Descriptions

For each group (or project) you can select one of the following levels:

gitlab notifications 4

Standard Notification Events

All users will be notified of the following events:

gitlab notifications 4

Creating a Group

Groups

Gitlab CE is arranged into different levels:

Groups > Subgroups > Projects > Issues

As volunteers and group members, you will be working primarily within your projects and with issues. If you would like to begin work on a new project, create it in the 007 Hosted Projects Group. If you want to experiment with GitLab CE and its functions, please use the 006 Sandbox Group. This space will be periodically cleaned up.

How to Create a Group

To create a group, follow the instructions here.

In the top menu, click Groups and then Your Groups, and click the green "New group" button.

group chat 1

Or, in the top menu, click on the "+" sign and choose "New group".

group chat 2

The New Group page will open and you will add the following information:

group chat 3

Group Name

The Group Name will automatically populate the URL. Optionally, you can change it. This is the name that displays in group views.

The Group Name can contain only alphanumeric characters, underscores, dashes, dots, and spaces.

Group URL

The Group URL is the namespace under which your projects will be hosted. The URL can contain only alphanumeric characters, underscores, dashes and dots. It cannot start with dashes or end in a dot.

Group Description

The description field is optional, but is incredibly helpful to communicate with others who may help with your projects.

Group Avatar

You may choose to upload a custom avatar for your group here. This will be auto-populated if you do not, and may also be changed later.

Group Visibility Level

The Visibility Level of the group is an important choice. GitLab allows owners to set a project’s visibility as public, internal, or private. When making this choice, please keep in mind that subgroups or projects cannot have a higher visibility level than that of the group in which they are created. We strongly suggest creating groups with visibilities of either Public or Internal.

Public Groups
These groups will be visible in the Explore Public Groups directory for all community members and potential members to explore. Any logged in user will have guest permissions on the repository.

Internal Groups
These groups are also listed in the Explore Public Groups directory, but are visible only to logged in users. Any logged in user will have guest permissions on the repository.

Private Groups
Private groups can only be viewed by group members (except for guests specifically invited to view the group). They will appear in the Explore Public Groups directory for group members only.

Mattermost

IEEE SA OPEN also hosts a Mattermost chat service. This can be accessed with the same credentials that you use to log in to the IEEE SA OPEN GitLab. If you would like to have a chat discussion space for your group, please check the box next to “Create a Mattermost team…” A Team will be created in Mattermost, as shown below. More information about joining IEEE SA OPEN Mattermost is available.

group chat 4

Group settings

After creating a group, you can manage its settings by navigating to the group's dashboard and clicking [Settings] in the left menu bar.

group chat 5

Creating a Project

Setting up Notifications

Projects

Gitlab CE is arranged into different levels:

Groups > Subgroups > Projects > Issues

As volunteers and group members, you will be working primarily within your projects and with issues. If you would like to begin work on a new project that does not belong in an existing group, please create it in the 007 Hosted Projects Group. If you want to experiment with GitLab CE and its functions, please use the 006 Sandbox Group. This space will be periodically cleaned up.

Create a Project

Most work in IEEE SA OPEN GitLab is done within a project. Files and code are saved in projects; and most features are used within the scope of projects. In GitLab, you can create a project for hosting your codebase, use it as an issue tracker, collaborate on code, and continuously build, test, and deploy your app with built-in GitLab CI/CD.

To create a project in GitLab:

Click the green New Project button at the top right of the Projects page, at the top right of a Group page or or use the [+] icon in the main navigation bar. These actions all open the New Project page.

gitlab projects 1

On the New Project page, choose if you want to:

  • Create a Blank Project.
  • Create a project using one of the available project templates.
  • Import a project from a different repository.

Blank Projects

To create a new Blank Project on the New Project page:

gitlab projects 2

On the Blank Project tab, provide the following information:

Project Name
Add the name of your project in the Project Name field. Note that GitLab CE allows the use of spaces, hyphens, underscores or even emoji when naming a project, but does not allow the use of special characters. When adding the name, the Project Slug will auto-populate. The slug is what the GitLab instance will use as the URL path to the project. If you want a different slug, input the Project Name first, then change the slug after.

Project Slug
The path to your project in the Project Slug field. This is the URL path for your project that the GitLab instance will use. If you choose to populate the Project Slug before the Project Name, the Project Name will auto populate when you fill in the Project Slug.

Project Description
The Project Description field enables you to enter a description for your project's dashboard, which will help others understand what your project is about. Although it's not required, filling this in is a good idea.

Project Visibility Level
Changing the visibility level modifies the Project's viewing and access rights for users.

Public Projects:

  • Public projects can be cloned without any authentication over HTTPS.
  • They will be listed in the Explore Public Groups directory for all community members and potential members.
  • Any logged in user will have Guest permissions on the repository.

Internal Projects

  • Internal projects can be cloned by any logged in user.
  • Internal projects will be listed in the Explore Public Groups directory, but will only be visible logged in users.
  • Any logged in user will have Guest permissions on the repository.

Private Projects

  • Private Projects can only be cloned and viewed by project members (except for invited Guests).
  • They will appear in the Explore Public Groups directory for project members only.

Initialize repository with a README
Selecting this option creates a README file so that the Git repository is initialized, has a default branch, and can be cloned.

When this information has been entered, click the green [Create project] button.

Built-in Templates

Built-in templates are project templates that are released with GitLab.

gitlab projects 3

To use a built-in template on the New Project page:

On the Create from template tab, select the Built-in tab.

From the list of available built-in templates, click:

  • The Preview button to look at the template source itself.
  • The [Use the template] button to start creating the project.

Finish creating the project by filling out the project's details. The process is the same as that for creating a Blank Project, above.

Importing a New Project

Guidelines for importing a project from a different repository are available. Projects can be imported from a variety of different sources.

Select the Invite Group tabgitlab projects 4

Sharing Projects with a Group

The primary mechanism to give a group access to a project is to make that group the owner of the project. If the project already belongs to another group, group sharing feature can be of use.

  • Use the left navigation menu to go to Members
  • Select the Invite Group tab
gitlab projects 5
  • Add the chosen group with the *maximum* access level of your choice.
  • Click Invite to share the project.
  • After sharing the project with the chosen group, the group will appear in the Project Members screen. The project will be listed on the group's dashboard.
gitlab projects 6

Note that you can only share a project with:

  • Groups for which you have an explicitly defined membership.
  • Groups that contain a nested subgroup or project for which you have an explicitly defined role.

Creating an Issue

Issues

Gitlab is arranged into different levels:

Groups > Subgroups > Projects > Issues

As volunteers and group members, you will be working primarily within your projects and with issues.

Issues are the fundamental medium for collaborating on ideas and planning work in the IEEE SA OPEN GitLab. They can be used to discuss the implementation of a new idea, track tasks and work status, accept feature proposals, ask questions, make support requests or bug reports, or elaborate on new code implementations.

Create a New Issue

There are many ways to create a new issue from within a project:

In any Project's Dashboard, click the Issues bar (shown in bright green below). The two views most frequently used to track are List and Boards. The List view is seen below. In this view, you can create a New Issue by clicking the dark green New Issue button at the top right.

gitlab issues 1

This will take you to the full-page New Issue form. Discussion of the different parts of the form is below in Elements of the New Issue Form.

gitlab issues 2

In the Boards view, a New Issue can be created by clicking the [+] icon in the Open column of the board, highlighted here in bright green.

gitlab issues 3

The New Issue form in the Boards view is smaller, but contains the same main elements as the full form. Its elements are discussed in the next section.

gitlab issues 4

From an open issue in your project, click the New Issue button (highlighted bright green below) to create a new issue in the same project. This button will take you to the full-page New Issue form, shown above in the List section.

gitlab issues 5

Elements of the New Issue Form

When you're creating a new issue, these are the elements to be completed:

  • Title - a short summary that describes the issue
  • Description - a complete description of the issue
  • Make Issue confidential - Most issues should not be confidential but available to the whole community.
  • Assignee - Issues should have assignees. If you don't know whom to assign the issue to, please assign it to yourself and ask for guidance when you next meet with your group, or reach out to the community in chat.
  • Due date - The date the task should be completed by.
  • Milestone - This is optional and not used by some groups.
  • Labels - The use of labels is discussed in further detail on a separate page.

Issue Duplication

To prevent duplication of issues for the same topic, GitLab searches for similar issues when new issues are being created.

When typing in the title in the New Issue page, GitLab searches titles and descriptions across all issues the user has access to in the current project. Up to five similar issues, sorted by most recently updated, are displayed below the title box.

Be Notified about an Issue

To keep track of an Issue that you are interested in, click on the issue in either List or Boards view. You will then see the screen below. Turn on notifications by toggling the switch at the bottom of the right sidebar (highlighted here in bright green). You will automatically receive notifications about issues that you create.

gitlab issues 6

Gitlab Project Management Basics

Managing Projects with Gitlab

The GitLab Issue Board is a software project management tool used to plan, organize, and visualize a workflow. It can be used as a Kanban or a Scrum board.

The Issue Board pairs issue tracking and project management, keeping everything in the same place, so that you don't need to jump between different platforms to organize your workflow.

Issue boards show your issues as cards in vertical lists, organized by their assigned labels. They can help you to visualize and manage your entire process in GitLab. Add labels, and then create the corresponding list for your existing issues. When you're ready, you can drag your issue cards from one step to another one.

An issue board will show you what issues your team is working on, who is assigned to each issue, and where in the workflow those issues are.

To let your team members organize their own workflows, use multiple issue boards.

gitlab tutorial 1

Use Cases for Issue Boards

You can tailor GitLab issue boards to your own preferred workflow. Here are some common use cases for issue boards.

Use cases for a Single Issue Board

With the GitLab Workflow you can discuss proposals in issues, categorize them with labels, and from there, organize and prioritize them with issue boards.

For example, let's consider this simplified development workflow:

  1. You have a repository that hosts your application's codebase, and your team actively contributes code.
  2. Your backend team starts working on a new implementation, gathers feedback and approval, and passes it over to the frontend team.
  3. When front end is complete, the new feature is deployed to a staging environment to be tested.
  4. When successful, the new code is deployed to production.

If you have the labels [Backend], [Frontend], [Staging], and [Production], and an issue board with a list for each, you can:

  • Visualize the entire flow of implementations from the beginning of the development life cycle through deployment to production.
  • Prioritize the issues in a list by moving them vertically.
  • Move issues between lists to organize them according to the labels you've set.
  • Add multiple issues to lists in the board by selecting one or more existing issues.

Use Cases for Multiple Issue Boards

With multiple issue boards, each team can have their own board to organize their workflow separately.

Scrum Team
With multiple issue boards, each team has one board. Now you can move issues through each part of the process. For instance: from [To Do] to [Doing] to [Done].

Organization of Topics
Create lists to order issues by topic and quickly change them between topics or groups, such as between [UX], [Frontend], and [Backend]. The changes are reflected across boards, as changing lists updates the labels on each issue accordingly.

Advanced Team Handoff
For example, suppose we have a UX team with an issue board that contains:
- To Do
- Doing
- Frontend

When finished with something, they move the card to Frontend. The Frontend team's board looks like:
- Frontend
- Doing
- Done

Cards finished by the UX team automatically appear in the Frontend column when they are ready for them.

Quick Assignments
Create lists for each of your team members and quickly drag issues onto each team member's list.

Issue Board Terminology

Issue Board
An issue board represents a unique view of your issues. It can have multiple lists, with each list consisting of issues represented by cards.

List
A List is a column on the issue board that displays issues matching certain attributes. In addition to the default [Open] and [Closed] lists, each additional list shows issues matching your chosen label. On the top of each list you can see the number of issues that belong to it. Types of lists include:

  • Open (default): all open issues that do not belong to one of the other lists. [Open] always appears as the leftmost list.
  • Closed (default): all closed issues. [Closed] always appears as the rightmost list.
  • Label list: all open issues for a label. A list with the appropriate label must be added for this to function.

Card
A card looks like a box on a list, and it represents an issue. You can drag cards from one list to another to change their label. The information you can see on a card includes:

  • Issue title
  • Associated labels
  • Issue number
  • Assignee

Permissions

Users with the Reporter and higher roles can use all the functionality of the Issue Board feature to create or delete lists and drag issues from one list to another.

How Issues are Ordered in a List

Issues on each board appear in an order in each list. You're able to change that order by dragging the issues up or down. The changed order is saved, so that anybody who visits the same board later sees the reordering, with some exceptions.

The first time a given issue appears in any board (that is, the first time a user loads a board containing that issue), it is ordered in relation to other issues in that list according to label priority. At this point, that issue is assigned a relative order value by the system, representing its relative order with respect to the other issues in the list. Any time you reorder that issue by dragging, its relative order value changes accordingly.

Also, any time that issue appears in any board, the updated relative order value is used for the ordering. It's only the first time an issue appears that it takes its ordering from the priority order mentioned above. This means that if two issues are reordered by any user in a given board inside your GitLab instance, the new order is maintained any time those two issues are subsequently loaded in any board in the same instance (could be a different project board or a different group board, for example).

This ordering also affects issue lists. Changing the order in an issue board changes the ordering in an issue list, and vice versa.

Creating an Issue Board

To create a new issue board:

Click the dropdown with the current board name in the upper left corner of the Issue Boards page.

gitlab tutorial 2

Click [Create new board] (highlighted in green above).

Enter the new board's name.

Deleting an Issue Board

To delete the currently active issue board:

Click the dropdown with the current board name in the upper left corner of the Issue Boards page.

Click Delete board.

Click Delete to confirm.

Focus Mode

Click the button with four arrows at the top right beside the dark green [Add Issues] button to toggle focus mode on and off. In focus mode, the navigation UI is hidden, allowing you to focus on issues in the board.

gitlab tutorial 3

Actions You Can Take on an Issue Board

  • Create a new list.
  • Delete an existing list.
  • Add issues to a list.
  • Remove an issue from a list.
  • Filter issues that appear across your issue board.
  • Create workflows. (See below.)
  • Drag issues between lists.
  • Drag and reorder the lists.
  • Change issue labels (by dragging an issue between lists).
  • Close an issue (by dragging it to the Done list).

If you're not able to do some of the things above, check to make sure you have been granted the correct permissions.

Create Workflows

By reordering your lists, you can create workflows. As lists in issue boards are based on labels, this process works out of the box with your existing issues.

A typical workflow using an issue board would be:

  1. You have created and prioritized labels so that you can easily categorize your issues.
  2. You have a bunch of issues (ideally labeled).
  3. You visit the issue board and start creating lists to create a workflow.
  4. You move issues around in lists so that your team knows who should be working on what issue.
  5. When the work by one team is done, the issue can be dragged to the next list so someone else can pick it up.
  6. When the issue is finally resolved, the issue is moved to the Done list and gets automatically closed.

For example, you can create a list based on the label of Frontend and one for Backend. A designer can start working on an issue by adding it to the Frontend list. That way, everyone knows that this issue is now being worked on by the designers.

Then, once they're done, all they have to do is drag it to the next list, Backend, where a backend developer can eventually pick it up. Once they're done, they move it to Done, to close the issue.

This process can be seen clearly when visiting an issue, since with every move to another list the label changes and a system note is recorded.

Drag issues between lists

When you drag issues between lists, different behavior occurs depending on the source list and the target list.

gitlab tutorial 4

Tips and Tricks

A few things to remember:

  • Moving an issue between lists removes the label from the list it came from and adds the label from the list it goes to.
  • An issue can exist in multiple lists if it has more than one label.
  • Lists are populated with issues automatically if the issues are labeled.
  • Clicking the issue title inside a card takes you to that issue.
  • Clicking a label inside a card quickly filters the entire issue board and show only the issues from all lists that have that label.
  • For performance and visibility reasons, each list shows the first 20 issues by default. If you have more than 20 issues, start scrolling down and the next 20 appear.

Using Labels

As the quantity of issues and merge requests increases in GitLab, it's more and more challenging to keep track of those items. This is where labels come in. They help you organize and tag your work so you can track and find the work items you're interested in.

Labels are a key part of issue boards. With labels you can:

  • Categorize issues and merge requests using colors and descriptive titles like bug, feature request, or docs.
  • Dynamically filter and manage issues and merge requests.
  • Search lists of issues and merge requests as well as issue boards.

Project Labels and Group Labels

There are two types of labels in GitLab:

  • Project labels can be assigned to issues and merge requests in that project only.
  • Group labels can be assigned to issues and merge requests in any project in the selected group or its subgroups.

Assigning and Unassigning Labels

Every issue and merge request can be assigned any number of labels. The labels are managed in the right sidebar, where you can assign or unassign labels as needed.

To assign a label to an issue or merge request:

  • In the label section of the sidebar, click Edit.
  • In the list, click the labels you want. Each label is flagged with a checkmark.
  • Find labels by entering a search query and clicking the magnifying glass icon, then click on them. You can search repeatedly and add more labels.
  • Click X or anywhere outside the label section and the labels are applied.

Creating Labels

Users with a permission level of Reporter or higher are able to create and edit labels.

Project Labels

View the project labels list by going to the project and navigating the menu at the left to Issues and then to Labels (highlighted in bright green). The list includes all labels that are defined at the project level, as well as all labels inherited from the immediate parent group. You can filter the list by entering a search query at the top and clicking the magnifying glass icon.

gitlab using labels 1

To create a new project label:

  • Click the New Label button (as shown on the screen above) to open the New Label screen.
gitlab using labels 2

Title
This text will appear on the label. Try to make it concise and clear.

Description
You can enter a description here to help your team better understand the purpose. This is optional.

Background Color
Select a background color by clicking on the available colors, or input a hex color value for a specific color.

  • Click the Create Label button to create the label.

You can also create a new project label from within an issue or merge request. In the label section of the right sidebar of an issue or a merge request:

gitlab using labels 3
  • Click Edit (highlighted green above) to open the Assign Labels menu.
  • Click [Create project label].

Name New Label
Fill in the Name New Label field. Note that you can't specify a description if creating a label this way. You can add a description later by editing the label (see below).

Assign Custom Color
Optionally, select a color by clicking on the available colors, or input a hex color value for a specific color in the Assign Custom Color field.

Add List
Click this checkbox if you would like to create a list on your issue board with this label as the descriptor.

  • Click Create.

Managing Project Labels

Editing a Label

Once created, you can edit a label by clicking the pencil icon.

You can also delete a label by clicking the three dots next to the Subscribe button and selecting Delete.

Caution: If you delete a label, it is permanently deleted. You will not be able to undo the deletion, and all references to the label will be removed from the system.

Promote a Project Label to a Group Label

If you previously created a project label and now want to make it available for other projects within the same group, you can promote it to a group label.

If other projects in the same group have a label with the same title, they will all be merged with the new group label. If a separate group label with the same title exists, it will also be merged.

All issues, merge requests, issue board lists, issue board filters, and label subscriptions with the old labels will be assigned to the new group label.

Caution: Promoting a label is a permanent action, and cannot be reversed.

To promote a project label to a group label:

  • Navigate to the project. In the menu at the left, navigate to Issues and then to the Labels in the project.
  • Click on the three dots icon next to the Subscribe button and select Promote to Group Label.

Group Labels

View the Group Labels list by going to the group and navigating the menu at the left to Issues and then to Labels. The list includes all labels that are defined at the group level only. It does not list any labels that are defined in projects. You can filter the list by entering a search query at the top and clicking the magnifying glass icon.

To create a group label, navigate the menu at the left to Issues and then to Labels and follow the same process as creating a project label.

Label Priority

Labels can have relative priorities, which are used in the Label Priority and Priority sort orders of the Issue and Merge Request List pages. Prioritization for both group and project labels happens at the project level, and cannot be done from a Group Label list.

From the Project Label list page, star a label to indicate that it has priority.

gitlab using labels 4

Drag starred labels up and down the list to change their priority, where higher in the list means higher priority.

Sorting Issues and Merge Requests

On the Merge Request and Issue List pages (for both groups and projects) you can sort by Label Priority or Priority.

By Label Priority

If you sort by Label Priority, GitLab uses this sort comparison order:

  1. Items with a higher priority label.
  2. Items without a prioritized label.

Ties are broken arbitrarily. Note that only the highest prioritized label is checked, and labels with a lower priority are ignored.

By Priority

If you sort by Priority, GitLab uses this sort comparison order:

  1. Items with milestones that have due dates, where the soonest assigned milestone is listed first.
  2. Items with milestones with no due dates.
  3. Items with a higher priority label.
  4. Items without a prioritized label.

Ties are broken arbitrarily.

More on Gitlab

If you’d like to learn more about GitLab, here are some resources that we’ve found helpful.

Video References

Articles

Mattermost Basics

IEEE SA OPEN has integrated the open source Mattermost chat service into GitLab CE. Mattermost resembles the Slack service popular in many businesses. Because chat is a rapid, real-time interaction, it can be incredibly useful for mentoring, troubleshooting and handling personal issues. IEEE SA OPEN has adopted a Code of Conduct to foster a healthy atmosphere.

When you are logged in to the IEEE SA OPEN GitLab, you may also visit the https://opensource-connect.ieee.org/ site to join in the community discussion on Mattermost. The same credentials act as a single sign-on (SSO) to both tools.

Click the Gitlab button on the right. If you aren't logged in to opensource.ieee.org, you will be guided to a login screen.

mattermost 1

On your first visit to Mattermost, you will be offered a list of teams that you can join. A team is a digital workspace where you can collaborate. Each team will host several channels for discussion.

Scroll through the team list to find a particular team you would like to join first. If there is none, Welcome is always a good place to start.

After choosing one team, you will be guided through a very brief three-screen tutorial. Guidance for joining additional teams follows.

mattermost 2

There are two places to join additional teams on the main Mattermost screen: the Team sidebar and the Main Menu. Both will return you to the screen above.

Joining More Teams

The Team sidebar (at the far right side of the main Mattermost screen) is a useful tool that allows you to switch between teams and also to join another team by clicking the [+] icon.

The example displayed also shows a second option for taking this action, the [Join Another Team] option in the Main Menu. This menu can be accessed by clicking on the three horizontal lines (or hamburger menu). This action will need to be repeated for each team you wish to join.

mattermost 3

Joining Channels

Channels are used to organize conversations across different topics. They are located on a panel at the left side of the Mattermost. All users are automatically subscribed to the Town Square/General channel and the Off-Topic channel in each team. The Town Square/General channel is for general conversations and the Off-Topic channel is a great place for socializing.

There are three types of channels: public channels, private channels, and direct messages. IEEE SA OPEN encourages our community members to create public channels, so that we can engage with one another and create new ideas. Channels correspond to the different projects in each GitLab group. These are places where you can ask questions, problem solve, and collaborate with other people working on similar projects.

mattermost 3

Messages

If you want to add more than just plain text, take advantage of Mattermost's support for Markdown formatting. This allows you to write formatted messages, insert tables, and provide related information while collaborating with other members. You can label your comments in the chat using hashtags so they can be searched for and referenced by anyone later on. You can use an @ symbol to tag someone in a comment if you are responding to them or need to direct a comment to them specifically in the open chat room.

Additional Account Settings

You may want to take this opportunity to configure your profile settings and notification preferences. Click on Account Settings at the top of the Main Menu to do so.

Profile Settings

Full Name
If you choose to enter a full name, it will appear in the direct messages member list. By default, you will receive mention notifications when someone types your first name. Entering a full name is optional.

Username
Usernames are unique identifiers appearing next to all posts. Your username is created when your IEEE SA OPEN GitLab account is created. It cannot be changed here.

Nickname
Nicknames appear in the direct messages member list and team management modal. You will not receive mention notifications when someone types your nickname unless you add it to the Words That Trigger Mentions in as noted in the Notifications section below.

Position
Nicknames appear in the direct messages member list and team management modal. You will not receive mention notifications when someone types your nickname unless you add it to the Words That Trigger Mentions in as noted in the Notifications section below.

Email
Nicknames appear in the direct messages member list and team management modal. You will not receive mention notifications when someone types your nickname unless you add it to the Words That Trigger Mentions in as noted in the Notifications section below.

Profile Picture
Nicknames appear in the direct messages member list and team management modal. You will not receive mention notifications when someone types your nickname unless you add it to the Words That Trigger Mentions in as noted in the Notifications section below.

Notifications

Desktop Notifications
Desktop notifications appear in the corner of your main monitor when there is activity in Mattermost.
When Desktop notifications are set to [Only for mentions and direct messages], an empty red circle is displayed over the upper right corner of the Mattermost dock icon when any message without an at-mention is received. A solid red circle with a post count is displayed when a message with an at-mention is received.
Choose what activity triggers a desktop notification. This setting applies globally, but this preference is customizable for each channel from the channel name drop-down menu. A notification sound can also be enabled for any activity that would trigger a desktop notification.

Email Notifications
Email notifications are sent for mentions and direct messages after you've been offline for more than 60 seconds or away from Mattermost for more than 5 minutes. Email Batching has been enabled, allowing user to select how often email notifications will be sent. All notifications received over a chosen time period are combined and sent in a single email.

Mobile Push Notifications
Push notifications can be sent to your mobile device if you have the Android or iOS app installed. You can choose the type of activity that will send a notification. By default, push notifications are sent [For mentions and direct messages]. If push notifications are sent [Never], the Mattermost setting to trigger push notifications depending on your status is hidden. Otherwise, you can choose when to send push notifications depending on your status. By default, push notifications are sent if your status is Away or offline.

Words That Trigger Mentions
By default, you receive notifications when someone posts a message that contains your non-case sensitive username or @username. You also receive notifications when someone uses the @channel, @all, and @here mentions. You can customize the words that trigger mentions by typing them into the input box. This is useful if you want to be notified of all posts on a certain topic, for example, marketing.

Reply Notifications
In addition to Words that Trigger Mentions, this setting allows you to receive mention notifications when someone replies to a thread that you started or participated in. You are considered to start a thread when you post a message to which other members of your team reply. You are considered to participate in a thread when you post a message using the reply button in an already existing thread.

More on Mattermost

Challenges

Logging onto Mattermost at https://opensource-connect.ieee.org/ takes you to the main page which contains a single button that says [GitLab]. Clicking on that button takes you to a page that appears to be the Gitlab sign-in. When you click on [sign in with IEEE login] and input login information, it then directs you to Mattermost. This process makes the user think they are logging into Gitlab, instead of Mattermost.