Introducing a document timeline component for JupyterLab
In collaborative environments, keeping track of changes and understanding the evolution of a document is crucial. This is especially true in fields like scientific computing and data science, where multiple contributors work together on complex projects. To address this need, we’re excited to introduce a document timeline component, a new feature that ships with the Jupyter Collaboration extension and enhances how teams interact with shared documents.
The timeline component is designed to give users control over a document’s history. Positioned as a slider in the JupyterLab status bar, it allows users to navigate through the timeline of a document. You can explore past versions, compare changes over time without altering the original document, and even restore specific versions. This feature is compatible with all types of shared documents within Jupyter, including notebooks, text files, and even third-party document types like JupyterCAD models.
How Does it Work ?
Co-editing of notebooks and other documents was introduced in JupyterLab 3.1 and has been improved and consolidated in subsequent releases. The feature can be enabled by installing the Jupyter Collaboration extension, which is built upon the Yjs framework, an implementation of CRDTs (Conflict-free Replicated Data Types). An important byproduct enabling real-time collaboration was the introduction of a journal of updates capturing all changes made by collaborators, which we leveraged to implement document timeline navigation.
Two key changes to Jupyter collaboration underlie the timeline component:
- The ability to fork the document history, which is required to visualize the past state of the document without altering it.
- The support of Undo/Redo operations in the Python implementation of Yjs, PyCRDT, through the implementation of an undo manager. While this was already available in Yjs, it was missing in PyCRDT until now.
As you move the slider to go back in time, the first operation that takes place is forking the document. Forking creates a new branch of the document at the selected point in history. This approach ensures that the most recent version of the document remains unaltered while you explore earlier versions. The forked version essentially acts as a sandbox where you can navigate through the document’s history, test out changes, and decide on the best course of action without modifying the main document.
When you navigate through the document’s timeline using the slider, the undo manager allows you to reverse or reapply any series of changes, stepping back through the document’s history without losing any information. If you decide to move forward again, the undo manager reapplies those changes in the exact order they were originally made, preserving the document’s integrity.
After reviewing the timeline, you can choose to restore a particular version at a selected timestamp. This restored version becomes the new active state of the document, effectively merging the changes from the forked branch back into the main document.
The document timeline component in the status bar offers an intuitive, flexible way to manage document history. Users can confidently experiment with different versions of their work, knowing that every action is reversible and that no progress will be lost. Whether you’re refining a piece of code, iterating on a design, or reviewing past contributions, the timeline equips you to iterate efficiently and effectively.
Seamless Integration with JupyterCAD
The document timeline is not just limited to text-based documents or notebooks. It was designed in a document-agnostic way, allowing its usage for any collaborative document. Consequently, it integrates seamlessly with JupyterCAD, JupyterLab’s extension for creating and manipulating 3D models. For engineers and designers, this integration is a game-changer.
In complex engineering projects, design iterations are common, and the ability to track the evolution of a 3D model is crucial. With the document timeline, users can effortlessly navigate through different stages of their design process. If a recent change in the 3D model doesn’t yield the desired results, the document timeline allows you to slide back to a previous version and pick up your work from there.
By combining the power of JupyterCAD with the document timeline’s history management, a team can achieve a more dynamic and flexible design process, ensuring that every idea is captured and every change is reversible. This integration exemplifies how the Jupyter Collaboration extension is enhancing not just collaborative editing but also specialized workflows in engineering and design.
A New Era of Collaboration in Jupyter
The document timeline is a significant step forward in our ongoing work to make Jupyter a user-friendly platform for collaborative technical computing. By leveraging the advanced capabilities of the PyCRDT undo manager, we’ve created a tool that simplifies document history management and enhances the overall collaborative experience.
As we continue to innovate and expand the Jupyter Collaboration extension, we invite the community to try out the new document timeline feature and share their feedback. Together, we can further refine these tools and ensure that Jupyter remains at the forefront of collaborative computing, empowering users across all disciplines to achieve more.
Acknowledgments
The development of the document timeline and its integration into the Jupyter Collaboration extension has been a true team effort, made possible by the dedication and expertise of many individuals. Special thanks are extended to the following team members for their invaluable contributions:
- David Brochart : For their innovative approach to integrating the undo manager within PyCRDT.
- Afshin T. Darian : For their supervision and feedback, which have been crucial in refining the functionality of the timeline component.
- Duc Trung Le : For their expertise in JupyterCAD and for ensuring that the timeline component seamlessly integrates with 3D model workflows.
About the Author
Meriem Ben Ismail just completed her Software Engineering degree at INSAT (National Institute of Applied Sciences and Technology in Tunisia) and her six-month internship as an open-source scientific software engineer at QuantStack.
Exploring a Document’s Timeline in JupyterLab was originally published in Jupyter Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.