Snap Changelogs offer developers and teams the opportunity to share recent progress with a manager, team, or customers. This three minute video describes the three problems that GitClear intends to help customers solve:

open_in_new

Three minute demo of setting up a Snap Changelog

Usually development work happens in a "black box" where even the project managers struggle at times to know what tickets their team is focused on. Snap Changelogs create transparency across an organization, allowing customers, vendors, and the team to participate in the excitement of watching a feature come together.

linkConcept

You can post Snap Changelog images anywhere an image can be posted! You might find value posting your published Snap Changelog to places like...

Anywhere that people might want to see what's new in the land of devs can be a good place to drop a Snap Changelog image.

linkConfiguring what will be shown by a Snap Changelog

The first step to setting up a changelog is to choose what you want the changelog to show.

The easiest place to create a new Snap Changelog is from the "Changelog Review" tab:

open_in_new

Buttons to create a new Snap Changelog

Before clicking one of these buttons, you will configure what repos and committers are to be shown by the changelog by picking a resource, team, date range, and optionally, a specific developer:

open_in_new

Chosen options when clicking button to create Snap Changelog will control what is shown in the changelog

linkConfigure publish options

Upon clicking the Snap Changelog icon, you'll be taken to a page that lets you configure the specifics of what you want to publish:

open_in_new

Choose from numerous possible charts when configuring your Snap Changelog

Until you hit "Publish Chart," the chart will not be visible except in your preview window. The entries shown in the changelog (when enabled) will choose from among all of your tickets, commits, and commit groups in the time range. Once your Snap Changelog is published, only the issues and commits that were published according to your chosen settings will be shown.

linkOption: Chart to Show

There are several types of charts that can be published. Most fall into three categories:

linkOption: Changelog individual entries

The "Top projects underway" section of the screenshots above is known as the "Changelog" in "Snap Changelog." You can read more about how to publish to the changelog here. When viewing the preview image, all commits and issues in the time range will be eligible to be shown in the Changelog, but once your chart has been activated (so it is visible to those who have the pseudonymous image URL), only published commits or issues will be shown.

All Changelog activity is sorted by the work with the greatest Diff Delta over the time Snap Changelog time period. Depending on the length of Changelog chosen ("short" is five entries, "medium" is 10 and "long" is 20), you'll see 5-20 of the largest commits and issues via the Changelog.

linkOption: Color Scheme

It's what it sounds like.

linkOption: Desired width

Controls the width of the image to be generated. The height of the image is dictated primarily by the Work Log length.

linkAdvanced Options

The Anonymize Committers option swaps out your developers' avatars on the Commit Activity Browser with autogenerated avatars. None of the velocity-based charts contain any information that could be used to identify committers. If you are sharing your Snap Changelog with external stakeholders or the general public, it's usually best to use the "Anonymize committers" in case there are developers on your team who prefer not to have their avatar seen by the customer base.

The Freshen Chart Automatically box controls whether the chart will dynamically update over time. Dynamically updating charts refresh their content at a rate relative to the type of GitClear subscription (from one hour to three days), so that they can be a continuous source of status. When the box is unchecked, it lets you save a particular moment in history that you might want to refer back to later.

linkPublish a Snap Changelog and copy image/HTML

Once you click the "Publish Chart" button on the Chart Configuration page, we will purge the preview image (which contains commits and issues that haven't been published) and kickoff generation a new Snap Changelog that will reside at a static URL and automatically update. When your chart is in the process of being generated, a placeholder image will be shown in your list of Snap Changelogs (Settings -> Account -> Snap Changelogs). It will look something like this:

open_in_new

Upon publishing a Snap Changelog, your final published image will begin to generate

After refreshing the page, you'll get buttons to copy an image URL or an HTML element:

open_in_new

After your image has generated, copy the image src or HTML

The image URL is useful if you want provide an src attribute to an img attribute you have on a page. If you don't yet have an image element, you can click "Copy HTML element" and you'll get something like this:

linkEmbedding a Snap Changelog

As of 2024, it is now possible to embed a Snap Changelog, as shown on Amplenote's Product Changelog page.

If you visit the Changelog Review tab and filter on a specific Snap Changelog, you'll get options like these:

open_in_new

The final option will copy the HTML for an embeddable iframe into your copy buffer.

In order to load the changelog and size it correctly, two additional steps may be necessary:

1. Ensure that CSP rules don't prohibit loading content from GitClear

Different web servers have different ways to specify the CSP (content security policy) rules for a loaded page. On the page where you want to embed a GitClear changelog, you will need to add a frame_src for https://www.gitclear.com. In essence, you need to ensure that your server response includes a header for Content-Security-Policy that specifies frame-src https://www.gitclear.com, potentially alongside other domains that are allowed to load into an iframe on the page.

If you're using Ruby on Rails with secure_headers, you can add to your frame source as follows:

2. Resize the changelog height using the iframe-resizer package from npm

After installing the package per the maintainer's instructions, you can resize the iframe containing the Snap Changelog with code something like:

This assumes that you have installed iframe-resizer 4.x, and that your iframe resides within a resizable-iframe-container div.

linkPublishing with a specific GitClear chart

If there's a report on GitClear that is especially applicable to your team's goals, you can click the Snap Changelog icon that appears next to most reports you'll find on GitClear:

open_in_new

Use the Snap Changelog icon to create a Snap Changelog that features almost any chart GitClear offers

linkSnap Changelog Security

Snap Changelogs are obfuscated using a pseudonymous UIUD. Read here to learn more about the anonymity afforded by a UUID, the short version is that "If you can generate one billion GUIDs per second, it would still take 36 years to have a 1.95e-03 chance of a collision."

Still, a published Snap Changelog can be seen by whoever gets ahold of the URL, so you will want to remain considerate of which charts will be published to the extent that the progress of your development efforts is considered a sensitive subject.

When publishing a Commit Activity Browser chart, we recommend considering the "Anonymize committers" checkbox to hide the avatars for your developers.