Open Design: Difference between revisions

← Older edit

Open Design (view source)

Revision as of 12:02, 5 November 2015

3,477 bytes added , 5 November 2015

edit

Ezoehunt

Confirmed users

195

edits

@@ Line 1: / Line 1: @@
 < intro here>
-== Instructions for Team Alopex ==
 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!
+[https://docs.google.com/presentation/d/1pbT7_J_iHuBZVbjt6pVZi0ZqliU4rqCq36l41NkmQgY See materials from the training session here].
+<hr>
 === Create a Github Account ===
 # Create your account at [http://www.github.com Github.com]
 # Email your Github handle to ehunt@mozilla.com - she'll add you to the Github org as a Member.
+# You'll receive an email invitation inviting you to join [https://github.com/fxos-product-design FxOS Product Design]. You need to accept the invitation before doing the next step - [[Open Design#Set up Github Desktop|Set up Git on your computer]].
+<hr>
+=== Set up Git on your computer ===
+To work with Github, you need to set up [https://git-scm.com/ Git] on your computer. For Product and Design teams, we recommend you use '''[[Open Design#Set up Github Desktop|Github Desktop]]''' to work with Git.
-=== Set up Github Desktop client ===
+===== Set up Github Desktop =====
-. '''Install [https://desktop.github.com/ Github Desktop client].'''
+:1. '''Install [https://desktop.github.com/ Github Desktop].'''
-. '''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.
+: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.
 ::[[File:01 move to apps.png|none|300px|Move to Applications]]
-. '''Click "Continue" on the welcome screen.'''
+:3. '''Click "Continue" on the welcome screen.'''
 ::[[File:01 open github.png|none|300px|Welcome to Github]]
-. '''Enter your Github credentials and click "Continue."''' We're not using the Enterprise options, so don't click that.
+: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."
 ::[[File:02 connect to github.png|none|300px|Enter Github credentials]]
-. '''Confirm your account and click "Continue."'''
+:5. '''Confirm your account and click "Continue."'''
 ::[[File:04 acct added.png|none|300px|Confirm Github account]]
-. '''Configure Git and click "Continue."''' Confirm (or edit) the name and email address you want associated with this project on Github.
+:6. '''Configure Git and click "Continue."'''
+::Confirm (or edit) the name and email address you want associated with this project on Github.
-::You can install the command line tools if you want to. But they're not required to use Github for Project Alopex.
+::You do not need to install the command line tools.
 ::[[File:05 configure git.png|none|300px|Configure Git]]
-. '''Click "Done" on the Find Local Repos 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.
+: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.
 ::[[File:06 find local repos.png|none|300px|Find local repos]]
-. '''You're done!"''' Github Desktop setup is complete. Skip the tutorial.
+:8. '''You're done!"''' Github Desktop setup is complete.
-::[[File:07 done.png|none|300px|Setup complete]]
+::Skip the tutorial (it describes a different workflow than the one we'll be using) and go to [[Open Design#Clone the Alopex Repository|Clone the Alopex Repository]]
+::[[File:07 done.png|none|550px|Setup complete]]
+<hr>
 === Clone the Alopex Repository ===
-# '''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.
+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.
-# '''Clone the remote Github repo.''' This makes a copy of the remote Github repo directory structure on your computer (a local repo).
-#* In Github Desktop, go to ''File > Clone repository''.
+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."
-#* 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.''
-# '''You're done!'''
+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.
 ::[[File:Open design example folder structure.png|none|400px|Example Directory Structure]]
+:2. '''Go to ''File > Clone Repository''.'''
+::[[File:19 clonerepo.png|none|650px|Clone Alopex repo]]
+: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."
+::[[File:20 selectrepo.png|none|550px|Select remote repo]]
+: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.
+::[[File:21 clone 1.png|none|550px|Browse to location]]
+::[[File:21 clone 2.png|none|550px|Browse to specific location]]
+:6. '''When you've navigated to the right folder, click ''Clone.'''''
+::Here's an example using the directory referenced above.
+::[[File:21 clone 3.png|none|550px|Clone it]]
+: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.
+::[[File:25 cloned repo.png|none|550px|Clone it]]
+::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.
+::[[File:26 cloned folder.png|none|400px|Clone it]]
 ''If you want to use the command line, go for it, though be mindful of how we're using Github.''
@@ Line 53: / Line 102: @@
 *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.
+<hr>
 === Example Workflow ===
@@ Line 63: / Line 115: @@
-=== Pushing to Github ===
+<hr>
-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.
+=== 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''.
+::::[[File:repo pull.png|none|550px|Repo Pull]]
+:::*Option 2: Click the "Sync" button in the upper right corner.
+::::[[File:sync.png|none|550px|Sync]]
+: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.
+::[[File:file_changed.png|none|550px|File changed]]
+:4. '''Switch to the "XX uncommitted changes" tab.'''
+::[[File:prepare commit.png|none|550px|Uncommitted changes]]
+: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.''
+::[[File:commit info.png|none|550px|Prepare commit]]
+: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."
+::[[File:commit info 2.png|none|550px|Commit]]
+::The screen will update to show that your changes were committed and there are no uncommitted changes.
+::[[File:committed.png|none|550px|Committed]]
-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.
+: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''.
+::::[[File:push.png|none|550px|Repo Push]]
-# '''Open Github Desktop client.'''
+:::*Option 2: Click the "Sync" button in the upper left corner.
-# '''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.
+::::[[File:push sync.png|none|550px|Push Sync]]
-# '''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.
-# '''Describe your changes.'''
-#* 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 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.
-# '''Commit (save) 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." Your changes are now saved as a package in your local repo.
-# '''Push to Github.''' 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.
-# '''Confirm your changes on Github.''' Visit the remote repo on the web and browse the folders where you expect to see the changed files. If it doesn't look the way you expect it to, repeat Steps 2-7. ''Note: once you get used to using Github, you probably won't need to do this step.''
-''Tips:''
+:8. '''Confirm your changes on Github.'''
-* 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 ensure that you don’t overwrite someone else’s change to the same file.
+::Go to the [https://github.com/fxos-product-design/alopex remote repo] and browse the folders where you expect to see your changed files.
-* 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.
+::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.''
-* 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.
+:''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 ===
@@ Line 100: / Line 184: @@
+<hr>
 === 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.
+* '''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.