Practice Abstract’s version control workflow

We've created a short exercise with sample Sketch files for contributors to learn about how to use the core functionalities in Versions projects. 

This exercise will walk you through:

  • Creating projects
  • Importing and linking library files
  • Creating branches and committing changes
  • Creating collections and annotating where you need feedback
  • Inspecting your artboards
  • Merging your branches 
  • Restoring to a previous commit
  • Deleting projects

Let's get started

You receive this design request from someone on your team. In this exercise, you’ll learn how to complete this ticket as if you're starting with Abstract for the first time.

CTA_request.png

Create a test project

You’ll first create a project to practice working in. If you want to keep the project invisible to the rest of your organization, you can follow step 4 but if you would like to keep the test project open for others on your team to test, you can skip this step.

  1. After you've created your Abstract organization, toggle to your company’s organization in either the desktop app or web app.
  2. Select New Project in the top right corner.
  3. Name your project “Practice: Website”.
  4. Check the box next to Make project private. This keeps your test drive invisible to everyone else in your organization.
  5. Click Create Project.
    Versions_create_website_project.png

Learn more about creating projects.

Download files and import import them into your project

We’ve created a few Sketch files (3 working files and 6 library files) for you to add to your practice project.

  1. Download this .zip file.
  2. Open the .zip file from your Downloads.
  3. In your “Practice: Website” project in Abstract, click Import Sketch File. Versions_Import_Sketch_file__2_.png
  4. Find the .zip file you just downloaded and opened.
  5. Select all files from the “Import to Website” project folder.
  6. Click Import 3 files.
    Versions_Import_Sketch_file_2__1_.png
  7. Click I understand.

Learn more about importing files.

Create a second project for your design system

We strongly recommend making a separate project for your design system, so all library files are consolidated in one central location. 

You can read about our libraries best practices that will help you get your libraries set up in the most efficient way for your team.

  1. In Abstract, select Projects from the left side pane.
  2. Select New Project in the top right corner.
  3. Name your project “Practice: Design System”.
  4. Check the box next to Make project private if you want this test project invisible to everyone else in your organization.
  5. Click Create Project.
    Versions_Design_System.png

Import the library files

After creating a project for your design system, you’ll import your library files.

  1. In your “Practice: Design System” project in Abstract, click Import Sketch File.
    Versions_Import_Sketch_files__1_.png
  2. Find the .zip file you just downloaded and opened.
  3. Select the “Buttons.sketch” file from the Import to Design System project folder.
  4. Select the Use as library box next to the file name.
  5. Click Import 1 file.
    Versions_Import_Library_files_2.png

  6. Click I understand.
  7. To add additional library files, click Add File.
  8. Select Import File…
    Versions_Import_Sketch_files__2_.png
  9. Select the rest of the library files, excluding the one you already imported. 
  10. Select the Use as library box next to each file.
  11. Click Import 5 files.
    Versions_Import_Sketch_files_3__1_.png
  12. Click I understand.

Link your library files

Now that your library files have been imported into your organization, you’ll need to link your libraries to your “Practice: Website” project.

  1. In Abstract, select the home button Screen_Shot_2021-04-05_at_11.53.29_AM.png  on the left.
  2. Select the “Practice: Website” project.
  3. Click Master in the left side bar.
  4. Go to the Files tab.
  5. Click Add File.
  6. Select Link Library…
    Linking_libraries_1.png
  7. Select “Practice: Design System”.
  8. Select the “Buttons.sketch” file, hold Shift, select the “Typography.sketch” file. This selects all the library files at once.
  9. Click Link Libraries. Your libraries will be listed under the Linked Libraries section.
    Linking_libraries_2.png

Learn more about linking libraries.

Create a branch

New work starts by creating a branch. Branches are the working copy of your master file where you can explore and edit designs in a project before sharing them with your team through committing and merging to master.

Once the files and libraries are all in place, let's work on the ticket you were assigned and make the requested edits.

  1. Under the Files tab, select the Homepage.sketch file.
  2. Click Edit in Sketch on the right.
    Create_a_branch_1.png

  3. Select Create a Branch.
    Create_a_branch_2.png

  4. Name your Branch “Homepage CTA”.
  5. Select Create branch. The Homepage.sketch file will open in Sketch.
    Create_a_branch_3.png

Read more about branching and our branching best practices.

Add a CTA button to the Homepage

With the Homepage file open in Sketch from Abstract, you can now make the edit that was requested.

  1. In Sketch, click Insert and hover over Symbols.
  2. Hover over Buttons > Button > Primary > and select Long.
  3. Place the button where you’d like. 
  4. Override the text with “Only $39/month”.

Commit your changes.

Committing saves your edits to Abstract and creates a log of commits that allows you to view the changes that have happened on every commit that has ever been made in a branch or master. 

  1. Click File > Save in Sketch.
  2. At the bottom of your Sketch window, click Commit Changes.
  3. In the Commit comment, write “Added CTA button to homepage”.
  4. Click COMMIT CHANGES.
    Screen_Shot_2021-04-20_at_1.02.51_PM.png

  5. Exit Sketch.
  6. Check out your commit in the Commits tab.
    Check_out_your_commit.png

You may see a Pending label next to the commit while the branch is syncing with the project. 

Learn more about committing and read our committing best practices.

Create a Collection

Collections help you present your work during design reviews and presentations. You’ll share your edits to the “Homepage” file and ask for feedback using a collection.

  1. In your “Practice: Website” project in Abstract, click the “Homepage CTA” Branch under Branches.
  2. Choose where you’d like to create a collection: on master or on a branch you own.
  3. Click New Collection...
    Create_a_collection__1_.png

  4. Select which artboard(s) you’d like to include in your collection.
  5. Click ADD 1 ITEM.
    Add_to_collection_3.png

  6. Fill in a name and description for the collection.
    Add_to_collection_2.png

  7. Close the window and your collection will be created.

Collections remain available under the Collections tab for each project.

To share your collection, you would click the Share button to copy the link.

When created on a branch that is then merged to master, the collection will be archived with the branch. You are able to add to the collection but the artboards in the collection will no longer update when artboards are changed. Create the collection on master if you want the collection to continue to update throughout the project.

Learn more about collections.

Annotate where you need feedback.

When you send your designs out for review, it can be helpful to point out exactly where you need feedback and annotations are an easy way to highlight these areas.

  1. Open the Homepage artboard in presentation mode by clicking on the artboard.
  2. Click the annotation icon Screen_Shot_2021-03-18_at_11.15.39_AM.png  in the comment box in the right side panel.
  3. Click or draw a rectangle over the area you’d like to annotate. A number will appear on your rectangle. This number will be attached to the comment you leave regarding that specific annotation. You can also resize the annotation if needed.
  4. In the comment box in the right panel, type “@Mila what do you think about black for this button?”. Markdown is supported in the comment box.
    Annotate_your_design.png

  5. Click the Comment button to submit your comment.
  6. Just for fun, react to your own comment by clicking the reaction tool and choosing an emoji.

Learn more about annotations and comments.

Check out the Inspect tab.

The Inspect tab gives you access to each design’s specs, styles, and code. Stakeholders and developers can access Inspect for any designs you’ve shared with them.

  1. Click on the artboard to open the layer detail.
  2. Click the Inspect tab.
    Check_out_the_inspect_tab.png

Hover over different parts of the artboard to see code-ready measurements for your designs. Additionally, a developer can download assets right from this tab. Just make the assets exportable in Sketch first.

Merge your branch

Once your branch is reviewed and approved, you’re ready to merge to master. Merging will save your edits and make those designs part of the master file. Any contributor can merge any branch to master.

  1. In Abstract, select Projects from the left side pane.
  2. Open your “Practice: Website” project.
  3. Select your “Homepage CTA” Branch from the left sidebar. 
  4. Click Merge branch... in the top right corner.
    Merge_to_master_1.png
  5. In the note field, write “Added a CTA button in black to the homepage”.
  6. Click Merge and Archive.
    Merge_to_master_2.png

Your update request is now complete and your ticket is ready to be closed out.

Read more about merging and our merging best practices.

Restore master to previous commit

You can revert a project’s master or your branches to any previous commit which returns the master or your branch to exactly how it looked at that point in time, while keeping the history of changes. 

At the last minute, you get feedback that Stem Society is no longer offering a subscription model. You need to rollback your merged changes to the homepage ASAP. 

  1. In the “Practice: Website” project, click Master in the left side bar.
  2. Click the Commits tab.
  3. Select the Commit called “Started using 6 files as libraries”.
  4. Click the Restore commit button Screen_Shot_2021-04-07_at_11.04.01_AM.png.
    Restore_commit__1_.png

  5. In the pop up window, you can Add a note (optional) to add additional content for the commit restore.
  6. For this request, write “Received feedback that we’re no longer doing a subscription model. Rolling back until we can explore other designs.”
  7. Click Restore Commit.
    Restore_commit_2__1_.png

Master is now restored to the designs right before you merged the homepage CTA design. 

Every time you commit in Abstract, you’re creating these bookmarks that you can roll back to. Commit early and often.

Learn more about restoring master to previous commits.

Delete your test drive projects

Feel free to practice branching, editing the Sketch files, committing your changes, and creating Collections until you have the hang of it.

Whenever you’re finished trying things out, delete both test drive projects.

  1. In Abstract, select Projects from the left side pane.
  2. Click the three dots … on the “Practice: Website” project card.
  3. Select Delete Project…
    Screen_Shot_2021-04-14_at_2.31.51_PM.png
  4. Type “CONFIRM DELETE”.
  5. Click I’m Sure, Delete the Project.
    Delete_project.png
  6. Repeat for “Practice: Design System”.

Deleting projects is a permanent action and deleted projects cannot be retrieved. There is also the option to archive your projects. For your working projects we recommend archiving your projects when you no longer need them to prevent any data loss.

Create your first working project

When you’re ready to set up your working projects, you can use the same steps listed here.