CodeTale - a solution for discussing your code & browsing discoursesTap into existing knowledge sourcesDifferent companies and teams are using various tools for collaboration and knowledge sharing. But is there any common one between them, a source which would always be available and, at the same time, is information-rich? It turns out there is: source control management system. Nowadays most the teams are using some form of pull request workflow to ensure proper code review and code quality. From those reviews, we can extract many useful comments and discussions, giving us great insight and additional context for the code. We just need to process them and find a way to make them much easier to explore. Documentation living with the codeIf we want documentation to be very accessible for every developer, we should provide it as part of the environment they are working in, usually it means some kind of editor or IDE. We know different people have different preferences and requirements, so CodeTale is going to support multiple tools Currently, that means Visual Studio Code, and the whole family of IntelliJ based products, but we are not going to limit ourselves to that. In those IDEs, we provide an effortless way to find and explore comments and discussions relevant to the viewed code. Thanks to that developer is always aware of past problems and considerations connected to the code in question. Furthermore, the implemented system intelligently links comments and discussions with the existing code regardless of new commits, branch changes, or changes in the code. Because of that developer does not have to track changes through history manually, but is always able to find the relevant part of the information immediately. Discuss the code with your colleagues onlineExploring potential locked in all the code reviews is great, but sometimes new problems and questions arise which might not have been addressed yet. In such situations, we want to give developers an option to ask new questions and commenting on existing code with valuable insights. CodeTale will automatically suggest people who are probably best suited to answer the question and notify about the one that which might concern them. To view and answer it, developers won’t need to leave their IDE — they can use all the benefits IDE gives them (like code navigation or history preview) to fully understand the question and answer it in the best possible way. Furthermore, discussions like that, regarding general issues, could be later explored by other developers, so knowledge is not lost and does not have to be rediscovered later. Table of Contents
Installing and configuring the extensionInstallationMake sure the project you intend to use CodeTale with has ⚠ CodeTale is in an early access phase. Before you can start using it, the extension will ask you to provide a passphrase to unlock further access. Contact us at codetale@virtuslab.com for more information. ConfigurationAt its core CodeTale uses a git repository to host discussions displayed by your code. This could be the same repository you use for versioning your code, or it can a separate repository on the same platform (GitHub, GitLab, BitBucket Cloud or BitBucket Enterprise). The first time you open a new project, you will be asked to provide information about this repository (see below for details). You can access and change these setting later by clicking the gear icon on the bottom of the CodeTale panel. To keep discussions in the same repository as your code, simply create a new branch in your repository and push it to the remote server. If you choose to host them externally, create a new repository on the same platform as your code repository. To populate the repository with discussions from pull-requests in your project, refer to Exporting comments from an existing project section below. Plugin Use these setting to configure how CodeTale looks and behaves.
Comments repository The repository you want CodeTale to read discussions from.
For example, if you keep your code in repository at the
Code repository The repository you keep your code in.
How to useIn IntelliJ IDEA look for "CodeTale" tab in Tool Windows Bar on the right and click it to open the CodeTale panel. In Visual Studio Code you will find it in the bottom right, or you can click the CodeTale logo on the sidepanel on the left to display a button, which will open the extension panel. Browsing discussionsThe extension panel displays comments for the file in focus, following your position in the file. Only the first comment in the discussion is displayed, when inactive. Click the cloud button to expand the responses to that discussion, or the "Reply" button to write your own response. When you bring a discussion into focus, the corresponding lines of code to which the discussion refers to will be highlighted. Writing a commentClicking the "Reply" button brings up an editor field. Tag other developers and use markup, code blocks and emojis to craft your reply and once you are ready click "Submit" to send the comment. Creating a new discussionWhenever you select a snippet of text or code, a cloud button will appear in the bottom left corner of the CodeTale panel. Click it to start a new discussion. Like with a comment, write your question or insight about the code in the editor field and click "Submit" to confirm.
Integration with a VCS platformExporting discussions from an existing projectTo take full advantage of CodeTale's capabilities and view the discussions of the past pull-requests, you will need to export these discussions from the platform of your choice to the branch you chose to host the CodeTale data (see Configuration). That will bring valuable insight into your usual interaction with your project's codebase.
To export the discussions from GitHub, GitLab, Bitbucket Cloud or Bitbucket Enterprise you can use CodeTale Converter available for download as a Maven package, or a Docker image. Using Docker
Using a jar
After running converter local copy of comments would be in ExamplesSame options can be used with Docker and JAR distributions. Following examples use JAR version, in order to switch to Docker replace To store comments in the same repository as the source, but in the different branch
If branch set with To store comments in a different repository than the source
To specify other branch, please add option -b <branch_name> as in the first example. Comments in a different repository, on a different serverCase when source repository is i.e. on ⚠ CodeTale plugin requires the source repository and comments repository to be on the same server. Use this option ony if you intend to work with a fork of the source repository, hosted on the same server as comments!
Convert PR from a specified rangeFor converting comments from a specified number range.
Default values for
Setting up CIFor continuous integration of discussions in pull-requests from your VCS platform into CodeTale, you can set up a CI workflow for committing the discussions, once a PR is closed and merged. This will require generating an access token for the CI runner to commit the discussions into the repository hosting CodeTale data. Below are attached examples for GitHub Actions and Gitlab CI. General rules of filling that scripts:
Gitlab CIAuthorization:
Example:
Setup GitHub ActionsAuthorization:
Paste and fill chosen yaml file to file in Using GitHub Action
To push converted comments to a repository other than the repository the action is run from, define
Using an image
Using Maven package
Contact usYour feedback is highly appreciated and will help us to improve CodeTale. Please send your questions and suggestions to codetale@virtuslab.com. |