How comments work on changesets and files

Beanstalk supports commenting in two places: changeset and file pages. On changeset page you can comment on the changeset as a whole or on a specific line of a diff. On file page you can only comment on lines of code. In this help article we will call comments that were made on lines of code inline comments.

Viewing comments

If a changeset contains inline comments an indicator will appear at the top left corner of the page. By default all inline comments are hidden (collapsed) in the code viewer. You can expand all of them at once by clicking Show inline link:

You will also see a comment indicator near each file name on changeset page and on file page as well. That means that the file contains inline comments. Clicking on that indicator will expand all inline comments for that file:

Each line of code that has inline comments will also have an avatar icon at the left side. A stack of avatars means that there are multiple comments. Clicking on the avatar will expand all comments for that line. It's the same as clicking on the line itself.

All comments that were made on lines of code on changeset page will also appear at the bottom of the page in a form of transcript for quick access. Each inline comment will be displayed with a chunk of code for which it was created to allow you quickly go through all comments without having to scan the source code.

Commenting on changesets

When you are on changeset page you can use the comment form at the bottom of the page to make a comment for the changeset as a whole. That comment will not be associated with a specific line of code.

You can also make comments on specific lines of code of one of the diffs of the changeset. To do that simply click on the line and comment form will appear:

Commenting on files

When you are on file page you can comment on a specific line of code simply by clicking on it. A comment form will appear together with the blame information for that line of code. Blame information allows you to address your comment to a person who changed that line last. You will also see when it was changed and in which commit:

Use cases

Commenting on changesets makes sense for reviewing code and pointing out issues with incoming commits.

Commenting on files makes sense for general discussions about the way certain pieces of code are implemented, even if they were in the repo for years. One great use case is a new employee who wants to find out how a certain class works. By using comments on file page he can notify a person who created that class (by using the blame information) and ask his questions. That comment will stick to that line of code until it changes and other team members might use that discussion in the future as some sort of code documentation.

Another use cases for file comments is making remarks for yourself or the team about certain pieces of code. If some function is too slow or some class is deprecated you can add a comment for it. Next time someone will be looking at that file in Beanstalk they will see your remarks.

Notifying users about comments

When creating a comment you can notify any user via email as long as they have read access to the repository. Use @username syntax to notify a user and @teamname to notify a Team of users. A suggestion popup will appear once you start typing a name to help you select. As a comment author you will be subscribed to replies automatically.

Every user or team that was mentioned in your comment will be subscribed to that changeset to receive future replies automatically. You don't have to mention same users over and over again. If you're commenting on file page then users will be subscribed to the changeset that appeared in the blame information.

If you're commenting on changeset page, Beanstalk will subscribe the committer automatically.

Users can unsubscribe from future email notifications any time by going to changeset page and clicking red unsubscribe link at the bottom of the page.

Subscribing to comment notifications for changesets and files

You can manually subscribe to all comments on a specific changeset by clicking green subscribe button at the bottom of the page.

You can also subscribe to all comments on a specific file by clicking the green subscribe button in the settings drop-down in toolbar:

Text formatting

Beanstalk uses Markdown formatting for comments. You can see a Markdown cheat sheet any time you're writing a comment by clicking a Markdown syntax link in the form. Previously supported Textile formatting is no longer supported.

Editing & deleting comments

As a comment author you can edit or delete your comment up to 15 minutes after it was created. Edit and delete links will appear next to a comment that's editable.

Comment persistence (stickyness)

To increase visibility of your comments we tried to make them as persistent as possible. If you made a comment on line 100 about the way certain function works and then someone committed a change to that file (without changing contents of your line) and your line has shifted to line 110, your comment should still be visible in Beanstalk. So even if the file's revision and line number are different from the time when you originally created your comment, it should still be visible.