Open Design

< intro here>

This section includes instructions for Alopex Product + Design teams.

Github Training Sessions

We set up 2 Github training sessions for FxOS design and product teammates:

• Monday, Nov 2, 2015
• Thursday, Nov 5, 2015
• Contact Jean for details on times!

See materials from the training session here.

---

Create a Github Account

1. Create your account at Github.com
2. Email your Github handle to ehunt@mozilla.com - she'll add you to the Github org as a Member.
3. You'll receive an email invitation inviting you to join FxOS Product Design. You need to accept the invitation before doing the next step - Set up Git on your computer.

---

Set up Git on your computer

To work with Github, you need to set up Git on your computer. For Product and Design teams, we recommend you use Github Desktop to work with Git.

Set up Github Desktop

1. Install Github Desktop.

2. Open Github Desktop.

Click the button to move Github Desktop to your Applications folder. Github Desktop will close briefly and re-open itself from your Applications folder.

3. Click "Continue" on the welcome screen.

4. Enter your Github credentials and click "Continue."

We're not using the Enterprise options, so don't click that.

If you're using two-factor authentication, you'll be asked to enter that before you can click "Continue."

5. Confirm your account and click "Continue."

6. Configure Git and click "Continue."

Confirm (or edit) the name and email address you want associated with this project on Github.

You do not need to install the command line tools.

7. Click "Done" on the Find local repositories screen.

This screen is asking if you want Github Desktop to know about your existing local repositories.

If you're new to Github, you won't have any local repositories. So just click "Done." If you already have some repos on your computer, select the ones you want Github Desktop to know about.

8. You're done!" Github Desktop setup is complete.

Skip the tutorial (it describes a different workflow than the one we'll be using) and go to Clone the Alopex Repository

---

Clone the Alopex Repository

Github repositories on your computer are called "local repos." Local repos are where you save your work. Then you "push" your work to the remote repo on Github, where other people can see it.

Repositories on Github are called "remote repos" because they are remote from the computer where you do your work. Remote repos are also sometimes called "upstream repos."

To get started with Alopex, you need to clone the remote repo for Alopex. When you "clone" the remote repo, you copy the current state of the remote repo and paste it to your computer as a new local repo.

1. Decide on a location for your local repositories.

Choose the location thoughtfully - moving a repo to a different directory after you've done Step 6 can cause problems later. See the example directory structure below.

2. Go to File > Clone Repository.

3. Select the remote repo you want to clone.

If you're new to Github, you will only see "alopex" as an option.

If you're a member of other Github repositories, you can search for "alopex" in the list.

Select the "alopex" repository, and then click "Clone alopex."

4. Navigate to where you want to put the cloned repo.

You may need to expand the down arrow to navigate to the right location.

6. When you've navigated to the right folder, click Clone.

Here's an example using the directory referenced above.

7. You're done!

When cloning is complete, you'll see history of the remote repo in the History tab.

You'll also see that "alopex" has been added under the header "Github" in the left column. If you clone other repos, they'll appear here too.

If you go back to your Finder and navigate to where you're storing your Github repositories, you'll see that a new folder called "alopex" has been added. Inside that folder are all the project files.

If you want to use the command line, go for it, though be mindful of how we're using Github.

• Designers in particular work alone on their files. So we're not (overly) concerned about collisions.
• We've created a simplified workflow so designers and other non-dev teammates can start using Github faster with a less steep learning curve.
• We're only using the master branch.
• We're not accepting pull requests (for now) -- this may change your workflow. You can just clone and pull/push to master.

---

Example Workflow

1. Create something you want to share in public.
2. Export files.
   • For designers, export as pdf or image.
   • For others, you might want to export as a pdf (e.g., if you've created slides) or just create text files - Github uses Markdown, so it's easy to format docs in a nice way.
   • If you were using the example directory structure above, you would export your file to Sites / FxOS_Product_Design / alopex / folder-name
3. Push to Github using instructions below.

---

Push to Github

This workflow is a simplified way to interact with Github. We're using this approach so team members who aren't familiar with Github can get used to it, before we move on to more sophisticated methods.

In this workflow, you're pushing directly to the master Github branch with no 2nd person review. As with Dropbox and Box, it’s possible to experience conflicts if someone else pushed the same file you did.

1. Open Github Desktop.

2. Get latest files from the remote repo.

As other people work on and push files to the remote repo, your local repo will become out of sync with the remote repo. So you'll want to "pull" files from the remote repo before you push any changes.

When you "pull" from the remote repo, Github Desktop looks at the difference between files in your local repo and files on the remote repo. If there is a difference, Github Desktop copies them to your local repo.

There are 2 ways to do this in Github Desktop:

• Option 1: Go to Repository > Pull.

• Option 2: Click the "Sync" button in the upper right corner.

3. Confirm that your changes appear in your local repo.

If you've already exported your work (pdf, image, etc) into your local repo, the screen will say "XX uncommitted changes."

If it doesn't say that, move (or copy) your changed files into your local repo.

4. Switch to the "XX uncommitted changes" tab.

5. Prepare your commit.

"Committing" means you are saving a particular state of your local repo. If you changed just one file, your commit consists only of that file. If you changed several files, your commit consists of all the changed files.

• Enter a title for your commit in the Summary field. For example, "Updated PTW spec."
• Enter a longer description for your commit in the Description field. Here you can describe the difference between your changes and the current versions on the remote Github repo. For example, you could copy your Change Log details into the Description field.

Note: the Summary and Description are displayed on the Github remote repo, so other people can see what you’ve changed.

6. Commit to your local repo.

When you're satisfied that you've got all the changes you want included in this commit, and you’re satisfied with the Summary and Description, click "Commit to master."

The screen will update to show that your changes were committed and there are no uncommitted changes.

7. Push to Github.

"Pushing" immediately sends your committed changes to the remote repo, and creates a new version for each changed file.

There are 2 ways to do this in Github Desktop:

• Option 1: Go to Repository > Push.

• Option 2: Click the "Sync" button in the upper left corner.

8. Confirm your changes on Github.

Go to the remote repo and browse the folders where you expect to see your changed files.

If it doesn't look the way you expect it to, repeat Steps 2-8. Note: once you get used to using Github, you probably won't need to do this step.

Tip:

• If you need to stop in the middle of Steps 2-7 and start over later, it's a good idea to start over again at Step 2. This helps to avoid merge conflicts.
• If you do experience a merge conflict (Github will tell you!), try googling to find a solution or reach out to some of your dev teammates to help you through it.

Gathering Feedback from Team and Collaborators

All files in the remote Github repo are visible to anyone on the web. So people can browse the repo and look at your files if they want to get an update on the project. But we'll get more (and more effective) feedback if we actively solicit it.

1. Copy the remote repo URLs for the files you want feedback on.
2. Open a new issue. Go to the repo’s Open Issues and click New Issue.
3. Enter a short descriptive title for the issue.
4. Label the issue. Be sure to use feedback wanted label. You can also use any of the other labels.
5. Add comments. Use the Comment field to provide context for your request for feedback and to describe the kind of feedback you're looking for. E.g., maybe it's specific - help me figure out this piece. It might be more broad - does Flow X work better than Flow Y?
6. Include the copied URLs in the Comment.
7. Post a message to the fxos-dev mailing list and include request for feedback with the URL to the new Open Issue. This way we'll hit contributors who may not know about our Github org.

---

Github Roles

• Members: Everyone on a project team is invited to the Github organization, e.g., FxOS Product Design, as a Member. Members can clone, pull, and push to any of the organization's repositories.

• Collaborators: Collaborators can clone and pull any repository. They can also open issues and comment on any issue.
  • Everyone on the web is a Collaborator. They just need a Github account to find our repos and participate in conversation. This means anyone inside or outside Mozilla can collaborate with us just by signing up for Github - we don’t need to explicitly add to them to our project repos.

• Owners: Owners create repos and add/remove Members. Owners can also make Contributors into Members. We’ll get into more details on Owners later.