135
edits
Changes
Activity Team/Git Tutorial (view source)
Revision as of 12:22, 12 December 2015
, 12:22, 12 December 2015Adding the GitHub Workflow and updated the page :)
(With ssh-keygen you can specify the name of your key file. Using this feature is not a good idea, because we haven't tested it. Keys should generally be located in <tt>~/.ssh/id_rsa.pub</tt> or <tt>~/.ssh/id_dsa.pub</tt>.)
(With ssh-keygen you can specify the name of your key file. Using this feature is not a good idea, because we haven't tested it. Keys should generally be located in <tt>~/.ssh/id_rsa.pub</tt> or <tt>~/.ssh/id_dsa.pub</tt>.)
=== Identify Yourself to Git ===
Git on your local system must know your email and name. It uses this when you commit a change, so that when you push or mail it others will know who did it.
If you do not use git on your system for any other project, you can configure git:
git config -f ~/.gitconfig user.email <email-you-used-for-registering-project>
git config -f ~/.gitconfig user.name <your-name>
You should only need to do this once on a system.
Otherwise, configure git in the repository:
cd ${SLUG}.git
git config user.email <email-you-used-for-registering-project>
git config user.name <your-name>
You should only need to do this once in a repository.
==GitHub Workflow==
=== Create a Project ===
=== Create a Project ===
You will create a project if you want to create a new activity or other feature which already has no related code. In case you want to make changes to the already present code, you will have to fork the repository(see the next heading)
Log in to GitHub at http://github.com and go [https://github.com/new here]. Choose a repository name, and write a description.
Log in to GitHub at http://github.com and go [https://github.com/new here]. Choose a repository name, and write a description.
=== Create Local Repository ===
=== Fork A Repository ===
A fork is a copy of a repository. Forking a repository allows you to freely experiment with changes without affecting the original project.
Most commonly, forks are used to either propose changes to someone else's project or to use someone else's project as a starting point for your own idea.
Forking a repository is simple, just go to the repository page and click the fork icon and that is it! Now you can see the repository in the list of your own repositories.
==== Propose changes to someone else's project ====
A great example of using forks to propose changes is for bug fixes. Rather than logging an issue for a bug you've found, you can:
Fork the repository.
Make the fix.
Submit a pull request to the project owner.
If the project owner likes your work, they might pull your fix into the original repository!
=== Create Local Repository (Clone) ===
Clone it from GitHub:
Clone it from GitHub:
Once you do this, you will have a local repository directory named ${SLUG}.git that shares the same history of changes (if any) of the repository at Sugar Labs. You should only need to do this once for each project and system. You can do it again if you need a fresh copy that has no changes.
Once you do this, you will have a local repository directory named ${SLUG}.git that shares the same history of changes (if any) of the repository at Sugar Labs. You should only need to do this once for each project and system. You can do it again if you need a fresh copy that has no changes.
=== Identify Yourself to Git ===
=== Keep your fork synced ===
You might fork a project in order to propose changes to the upstream, or original, repository. In this case, it's good practice to regularly sync your fork with the upstream repository. To do this, you'll need to use Git on the command line.
When you fork a project in order to propose changes to the original repository, you can configure Git to pull changes from the original, or upstream, repository into the local clone of your fork.
Navigate to your repository folder from the terminal and then type,
git remote -v
and press Enter. You'll now see the current configured remote repository for your fork.
Next, Type
git remote add upstream
and then paste the URL of the main repository (from where you made your fork) and press Enter. It will look like `git remote add upstream https://github.com/Someone/something-anything.git`
To verify the new upstream repository you've specified for your fork, type
git remote -v
again. You should see the URL for your fork as origin, and the URL for the original repository as upstream.
Now in order to sync with the upstream URL that you added above, you will have to fetch the branches and their respective commits from the upstream repository. Commits to master will be stored in a local branch, upstream/master.
git fetch upstream
Check out your fork's local master branch.
git checkout master
Merge the changes from upstream/master into your local master branch. This brings your fork's master branch into sync with the upstream repository, without losing your local changes.
git merge upstream/master
==== Note: ====
1. If your local branch didn't have any unique commits, Git will instead perform a "fast-forward":
2. Syncing your fork only updates your local copy of the repository. To update your fork on GitHub, you must push your changes.
=== Branches ===
When you're working on a project, you're going to have a bunch of different features or ideas in progress at any given time – some of which are ready to go, and others which are not. Branching exists to help you manage this workflow.
When you create a branch in your project, you're creating an environment where you can try out new ideas. Changes you make on a branch don't affect the master `branch`, so you're free to experiment and commit changes, safe in the knowledge that your branch won't be merged until it's ready to be reviewed by someone you're collaborating with.
==== Tip ====
There's only one rule: anything in the master branch is always deployable.
Because of this, it's extremely important that your new branch is created off of master when working on a feature or a fix. Your branch name should be descriptive
=== Commits ===
Once your branch has been created, it's time to start making changes. Whenever you add, edit, or delete a file, you're making a commit, and adding them to your branch. This process of adding commits keeps track of your progress as you work on a feature branch.
Commits also create a transparent history of your work that others can follow to understand what you've done and why. Each commit has an associated commit message, which is a description explaining why a particular change was made. Furthermore, each commit is considered a separate unit of change. This lets you roll back changes if a bug is found, or if you decide to head in a different direction.
In your local repository, find out from git what files you changed:
In your local repository, find out from git what files you changed:
Add any files that are new or changed:
Add any files that are new or changed:
git add ...
git add <file path>
or too add all the files
git add --all
Tell git to collect the changes into a commit:
Tell git to collect the changes into a commit:
=== Push Changes ===
=== Push Changes ===
Your changes have to be pushed from your local repository to the repository at git.sugarlabs.org so that others can see them there.
Your changes have to be pushed from your local repository to the repository at github so that others can see them there.
git push
git push
You must do this for every set of changes you make, when you want to synchronise with other developers or prepare for a release.
You must do this for every set of changes you make, when you want to synchronise with other developers or prepare for a release.
=== Pull Request ===
In order to request the repository's owner to consider the changes that you made in your repository and include them in the main code, you will need to make a pull request. In order to do this, just open up your repository page, `https://github.com/yourUserName/RepoName`, now you will a line just above the contents saying something like `This branch is 1 commit ahead of walterbender:master.` and you will also thus be able to see a button to create a New Pull Request for the same, then you can review the changes made and the commits to be added in that request and also a message box for the message you would want others to read, describing the changes you made. Then you can proceed to successfully creating a pull request, which will then be reviewed by others. And you can discuss on the very same page regarding whatever needs to be done. And if all is perfect, your pull request will be merged into the main code!
to update the .mo files after updating the .po files
== Other Notes ==
== Other Notes ==
git push --tags
git push --tags
[[Category:Activity Team]]
[[Category:Activity Team]]
[[Category:HowTo]]
[[Category:HowTo]]