Open Design

< intro 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.

Set up Github Desktop client

1. Install Github Desktop client.
2. Open Github Desktop and add your Github account details.
3. Decide on a location for your local repositories. Choose the location thoughtfully - moving a repo to a different directory after you've done Step 4 can cause problems later. See the example directory structure below this section.
4. Now you’ll make a copy of the remote Github repo’s directory structure on your computer (a local repo).
   • In Github Desktop, go to File > Clone repository.
   • Select the remote repo you want to add, and click Clone <repo name>.
   • Github Desktop will ask you the destination for the cloned repo. Browse to the directory where you intend to store your repos. With the example directory structure below, you would browse to Sites / FxOS_Product_Design
   • Then click Clone.
5. You're done!

Example Directory Structure

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.

Pushing to Github

This workflow is a simplified way to interact with Github. We're using this simplified 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 branch (source of truth) with no 2nd person review. As with Dropbox and Box, it’s possible to overwrite someone else’s changes to the same file if you’re not careful.

1. Open Github Desktop client.
2. Get latest files from Github. In Github Desktop, go to Repository>Pull. This grabs any files from the remote repo that differ from what you have in your local repo.
   • Confirm that your changes appear in your local repo.
   • If you've already exported your pdf (or image) into your local repo, the top bar of the Github Desktop client will say "XX uncommitted changes."
   • If it doesn't say that, move (or copy) your changed files into your local repo.
3. Describe your changes.
4. If it's not already highlighted, click the "XX uncommitted changes" tab.
   • Type a descriptive summary of your changes in the Summary input field.
   • Add a description of the changes in the Description field. 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 that the Summary and Description text are displayed in Github History, so other people can see what you’ve changed.
5. Commit (save) your local repo.When you're satisfied that you've got all the changes you want included in the commit, and you’re satisfied with the Summary and Description, click "Commit to master." Your changes are now saved as a package in your local repo.
6. Now go to Repository>Push. This immediately sends the package of changes to the remote Github repo and creates a new version for each changed file.
7. You can confirm that your changes appear in the remote Github repo by visiting the remote repo on the web and browsing the folders where you expect to see the changed files.

Tips:

• If you need to stop in the middle of Steps 3-9 and start over later, it's a good idea to start over again at Step 3. This helps ensure that you don’t overwrite someone else’s change to the same file.
• For now, please don't use Github's fork or pull request functionality. As we’re all learning how to use Github, we want to stick to basic Github commands for now - clone, pull, commit, push.
• Within the Github Desktop client, please don't use the Sync button, as well as the Publish/Unpublish options in the Branch menu. These do unexpected things that impact the remote repo.

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. Go to the repo’s Open Issues and click New Issue.
3. Create 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. 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 including 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 project's Github repo as a Member. Members can clone, pull, and push to any repositories.

• Collaborators: Everyone on the web is a Contributor. They just need a Github account to find our repos and participate in conversation. Contributors can clone and pull any repository. So everyone inside and outside Mozilla can collaborate with us just be signing up for Github - we don’t need to explicitly add to them to our project...

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