How we built our GitHub app

Swimms GitHub app helps developer teams create, maintain, and find documentation as part of the development workflow.

When our team at Swimm began designing Swimms GitHub app, we needed to identify the best moment to interact with users. We knew, for example, that running and notifying users on every open branch can be annoying, and we wanted to make the experience simple and enjoyable. Moreover, we understood that we had to find the window of opportunity for developers - the best time when software engineers were looking for checks, reviews, and comments.

Design of Swimms GitHub App

Our team at Swimm started designing the GitHub app integration in 2021, keeping in mind that most interactions happen during Pull Requests because its usually the last point the code can be verified before it is merged into the main branch and deployed. But its also the first time when software engineers push their code and mark it as ready for review.

The initial version of Swimms GitHub App ran our Swimm Verify check whenever a PR was opened or an open PR was updated. This allowed us to make sure the documentation on the branch would stay up to date so that code changes would not require an update to the documentation.

Continuously improving Swimms GitHub App

Since then, we have added quite a few capabilities and features. Today were covering Swimms GitHub app features one by one.

Accepting Auto-synced changes from GitHub

Swimm's patented Auto-sync algorithm analyzes what happens in your codebase. When Swimm Verify check recognizes Auto-sync documentation changes, users are notified via a comment on your pull request. You can then trigger a Swimm Commit by clicking the Approve Auto-sync button in the check, which accepts all Auto-synced docs from the GitHub App.

Automatic Auto-sync approval

Weve taken the Auto-sync feature one step further. In the GitHub app settings, you can set up automatic Auto-sync approval. Swimms GitHub app will automatically accept Auto-sync changes, committing them to your open pull request in a dedicated commit. Clients rely on Swimms trusted patented Auto-sync algorithm to automatically update their documentation with this feature.

New doc notifications

Since tracking and locating documentation is challenging, we designed a feature for New Doc Notifications: you can set an alert on Slack or via email whenever a new document is created and merged to your main branch. This helps keep track of new documentation in your repo and allows you to invite other members of your organization to read and learn more about new documentation. Weve found that this encourages a better overall understanding of the codebase.

Draft Documents from Pull Requests

We all know too well that documentation is usually an afterthought, or something completed after writing tests and making code review requested changes to your PR.

This is exactly why Swimms GitHub App analyzes your code changes, and when a Pull Request is interesting enough to document, we notify you with a comment and encourage you to create it. With a single click on the Review Draft in App button in our comment, you go into Swimms Web App. All the code changes from your Pull Request are added to a document, and all thats left for you is explaining what the code does. There are no rules for how to do this, but ideally, you would want to arrange it in an order that tells a story.

Doc recommendations

When you change code that has relevant documentation, Swimms GitHub app recommends documentation for you to review. This helps users access documentation about specific code changes by alerting you to relevant documentation on PRs.

Here are a few examples you might see: a doc is recommended to you for your E2E testing guide whenever someone changes a covered test; the CI deployment documentation is recommended when someone changes a configuration script; a fragile piece of code changes, and you are alerted to documentation that references an Incident Report.

Swimm Verify on PR changes only

We created an option to run Swimm Verify only on files that are changed in the Pull Request.

Heres why: because we know that sometimes things break on the main branch. Perhaps a merge conflict or two competing changes are going on simultaneously. And we know that this can happen with your documentation as well. While these changes might take some time to be fixed, they might otherwise fail our Swimm Verify check across your repository, even on unrelated Pull Requests. So we suggest that it is a worthwhile option to turn this feature on until issues with your main branch are resolved. This feature helps our clients avoid unnecessary delays.

Disabling comments

Our engineering teams work in a fast-paced environment; we move quickly, frequently break things, and always work on bug fixes.

Therefore, we designed Swimms GitHub app with an option to disable comments. This helps reduce the number of notifications that youll be sent during busy deadlines and crunch time. And then, of course, you always have the option to enable the comments again whenever you wish.

Integrations with other tools

Swimm partnered with Atlassian Compass - bringing Swimm to Compass ecosystem so that you can see your latest documentation status for all your distributed services from a single place. You can also use Swimms Compass Integration to link Swimm documentation to the Compass component.

Swimm is currently integrating additional tools to facilitate understanding the bigger picture of your software development status with your Swimm documentation included.

Doc hooks - coming soon

Getting recommendations for a relevant document to existing code is helpful. But what about newly added code? There should be a way to locate documentation in situations such as:

• When a new database migration is added link to your database migration policy
• When the configuration file is modified link to your environment variable update process walkthrough
• When a new record is added to your Infrastructure as a code setting link to your explainer on how to verify it will be deployed correctly.

Our team at Swimm is currently working on solutions to these exact problems. We are testing an alpha version of a feature that will recommend a specific document when a certain file is changed or something is added to a folder. Stay tuned!