Collaboration Tools

Writing is often a collaborative exercise, and Atlas makes it easy to work together on a project, track everyone’s changes, and incorporate those changes into a master set of project files. Here is an overview of how you can use Atlas to collaborate.

Adding New Collaborators

To grant others access to your project so that they can edit the text or generate builds, you will need to add them as collaborators. To do so, navigate to your project, and click on the Project Settings button. Then, in the Add New Collaborator section, enter the email address of a person you wish to add to the project. Choose "Owner" from the drop-down, and then click Invite. Repeat for each user you’d like to add. Owners have full permission to edit all files in all branches of the project.

If an invitee is already an Atlas user, she will immediately be granted access to the project and see it on her Projects dashboard. If she is not yet an Atlas user, Atlas will send her an email asking her to sign up, and once she does so, she will see the project on her Projects dashboard.

Working in Branches

Branches are an important and powerful feature of Git, as they allow users to work independently and concurrently without worrying about disrupting others' work or introducing file conflicts.

To merge branches, you’ll need to have Git installed on your computer. See #atlas-git for instructions.

In Atlas, the canonical set of files is stored on the main branch of the project. If you have different workflow needs, speak with your editor.

Collaborators with Owner status have the ability to make changes directly to the main branch. (Owners can also make their own branches, if they’d rather not make changes directly to the main branch.) It is recommended that anyone contributing to the project be set as an Owner.

Creating and Selecting Your Own Branch

There are two methods to create your own branch.

The first is in the Atlas Web Interface, click on "Add a branch" in the upper-right corner:

The Add a branch a button in the Atlas Web interface

Here’s what you’ll see after clicking "Add a branch":

Clicking Add a branch takes you to your new branch

The new branch is labeled with your username (e.g., "asumner" in the upper-left corner, as shown above). To switch between branches, use the dropdown menu, as shown here:

Branch selector drop-down menu

The second is in a local clone of the repository, run the following commands:

  1. git checkout -b branch_name

  2. git push origin branch_name

In the Atlas web interface, you’ll see your new branch "branch_name" in the drop-down menu in the upper-left corner.

Merging Changes Into Main

Do not use the "Send Edits to Main" feature on the Atlas web interface to compare or merge changes. It is not fully functional and may result in lost work.

After creating a branch, you are free to make any kind of change, including adding or deleting files, fixing typos, adding new /images, etc.

To merge the changes in your branch into the main branch, follow these steps in your local clone of the repo:

  1. git checkout main—Sets the active branch to main.

  2. git pull origin main—Gets the most recent commits from origin (i.e., Atlas, if you are working in a local repository cloned from Atlas and have not changed the name of the remote).

  3. git merge ``branch_name`—Merges the changes from the branch `branch_name` into the `main branch.

  4. git push origin main—Pushes your changes back to Atlas.

Merge Conflicts

If there is a conflict between what was in your branch and what’s in main, there will be a merge conflict. Merge conflicts will be indicated in your file by the following:

<<<<<<< HEAD
original text
=======
conflicting text
>>>>>>> branch_name

To fix the merge conflict, replace the text above with the correct text, and then commit the changes.

Activity Log

When multiple people are working on a project it’s helpful to know what other people are doing—Atlas can help with that. Click the Activity button at the top-right of your project dashboard, and you’ll see a log of everything that has been happening on the project lately:

The activity log shows a list of commits and their authors

This page displays when collaborators have made changes, which files were changed, and in which branch. This information can help you keep track of what others are working on, and when various documents were last edited.

Best Practices

Atlas’s collaboration tools work best when paired with effective communication and organization among collaborators on a project. Below you’ll find some suggestions, tips, and tricks from the Atlas team to help you create and manage a successful workflow for your Atlas projects.

Workflow

  • Avoid merging more than one collaborator submission at a time. While projects may have multiple owners, designating one person at a time to review submissions and merge them into main will streamline your workflow and prevent wasted time resulting from multiple people reviewing the same submission concurrently.

  • Coordinate who is working on which documents within a project at a given time. The more people working on the same document at once, the more difficult review can become for the project owner. Use the Activity log to help keep track of who is doing what to reduce user headaches!

  • Opt for multiple smaller submissions rather than fewer large submissions when possible. Along with descriptive messages, submitting changes for review in smaller chunks allows the main file set to be updated more frequently, keeps other collaborators up to date, and reduces the chance of multiple collaborators making contradictory changes.

  • If you are working locally, git pull regularly to make sure your local clone is up-to-date with main.

Using the Git Collaboration Tools

  • Add a descriptive message when pushing your commits. While these notes are optional, it’s useful to keep track of the kind of work contained in each submission to main. It helps eliminate confusion and increases efficiency when merging.

  • Work directly in main when appropriate. Are you starting a new project by yourself, or are you the only owner on a project? You can save time by working directly in the main branch. Atlas will still keep the full history of your work and display updates in the Activity log when you make changes.

  • Ask collaborators to set up an avatar. This makes it easy to identify at a glance who has created which builds, left text comments, etc. Set this up from your account settings page. Atlas uses Gravatar, so if you already have an account under your Atlas account email address, you’re already done.