Meadville Space Center
Welcome, Guest. Please login or register.
October 21, 2020, 05:47:34 PM

Login with username, password and session length
Search:     Advanced search
Gemini 060615 released!
25068 Posts in 2094 Topics by 2266 Members
Latest Member: twa517
* Home Help Search Login Register
+  Meadville Space Center
|-+  Project Apollo - NASSP
| |-+  Project Apollo - NASSP Development (Moderators: movieman, Tschachim, Swatch, lassombra)
| | |-+  DEVELOPERS, READ THIS FIRST: WORKING WITH GIT / HOW TO GET A GIT CHECKOUT
« previous next »
Pages: [1] Print
Author Topic: DEVELOPERS, READ THIS FIRST: WORKING WITH GIT / HOW TO GET A GIT CHECKOUT  (Read 6234 times)
dseagrav
Project Admin
Hero Member
*****
Posts: 1118


View Profile
« on: July 29, 2015, 09:38:52 PM »

NASSP has moved from CVS to Git. Our main development repository is hosted on Github and a backup repository is maintained on Sourceforge.
The backup repository is automatically updated from the main repository every 12 hours (midnight and noon US/Central) by a script running on my server.

HOW TO GET A GIT CHECKOUT:

1) Install git for Windows. MAKE SURE THAT WHILE YOU ARE INSTALLING GIT, WHEN IT ASKS YOU WHAT TO DO WITH LINE ENDINGS, YOU TELL IT TO LEAVE THEM ALONE. THIS IS NOT THE DEFAULT OPTION.
We are NOT a cross-platform project. If you mess this up, you will make a mess for everyone else whenever you commit your work.
2) Install Orbiter, set it up, make it run, install OrbiterSound and your visualization plugin of choice and whatever else you will need.
2a) It would be a good idea to back up Orbiter at this point so if you have to start over for some reason you don't have to reinstall all that stuff.
3) Open a command prompt and cd to where you put Orbiter.
4) Type "git init" and push enter to make a new local repository.
5) Type "git remote add origin https://github.com/dseagrav/NASSP.git" and push enter to tell git about the github repository.
6) Type "git fetch origin" and push enter to download data from the repository.
7) Type "git checkout -b master --track origin/master" and push enter to tell git you want to follow the main branch. If git complains about files being in the way, delete them and do this again until it works.
8) Type "git reset origin/master" and push enter to make the latest changeset current.
9) Close the command prompt, you are done!

Beyond this point, all of the things I explain can be done with the GUI, but I will explain them using the command line so it is understood what is going on.
The GUI options generally follow the command line actions.

These posts will be updated as things change. Feel free to post questions/comments.
« Last Edit: August 01, 2015, 09:24:38 PM by dseagrav » Logged
dseagrav
Project Admin
Hero Member
*****
Posts: 1118


View Profile
« Reply #1 on: July 30, 2015, 11:29:32 PM »

WORKING WITH THE MASTER BRANCH:

Your git repository, if set up as above, is local. You have a remote repository named "origin" that contains everyone else's changes. To have their changes downloaded to you, the command is "git fetch origin". This downloads all changes in all branches on the server into your local repository, but it does NOT change your working copy. You can do this as often as you feel necessary. To actually incorporate these changes into your working copy, you merge them in. The command for this is "git merge origin/master". If there are any conflicts, they are handled as CVS did before, with the changed blocks inside <<<<<<< and >>>>>>> with ======= dividing them. Edit the file to resolve the conflict and commit the result to complete the merge.

There is a "git pull" command that works similarly to fetch/merge in a single step, but it does not download information about other branches and doesn't give you the chance to review changes before the merge. You can use this if you wish, but doing fetch/merge instead gives you more information about what is going on.

When you are done changing your working copy and want to push your changes for everyone else, you need to first commit your changes locally. The command for this is "git commit -a" and it works like cvs commit did, except that git will open a unix-like editor to get your commit message instead of notepad. Type your change message, then type escape-:-w-q-enter to save changes and close it. (If you decide you don't want to commit after all, the sequence of keys to cancel the editor is escape-:-q-!-enter. Having an empty commit message makes git cancel the commit.) The -a tells git to automatically add any files you have modified or deleted to the changeset, but it will NOT automatically add new files. To add new files to your changeset you have to use "git add" just like how you had to use "cvs add" before. If there are any untracked files you will be told about them in the commit message comments. You can safely ignore this list if none of the files on it are involved in your changes. You may consider adding files to be ignored to the .gitignore file in the orbiter directory.

You can commit as many times as you like before pushing your changes to the server. When you have committed all of your work and are ready to push your commits to the world, the command is "git push origin master". All of your changes will be transmitted. If you get a message saying that the remote cannot fast-forward, that means someone else committed changes you do not have, and you need to do a fetch/merge to bring your work into sync.

Pushing to the github now causes a build to be done for the branch pushed. If successful, a release is made to github. I'm still working on the mechanics of this. The status of the builds is at http://www.lunar-tokyo.net/NASSP/.
« Last Edit: August 29, 2015, 11:18:33 PM by dseagrav » Logged
dseagrav
Project Admin
Hero Member
*****
Posts: 1118


View Profile
« Reply #2 on: July 31, 2015, 12:51:10 AM »

WORKING WITH YOUR OWN BRANCH:

A branch is an alternate version of of the project, with its own changesets. Branches in CVS were complicated and a chore, they had to be created on the server and did not track merges. Branches in git are cheap. They can be freely created and destroyed at any point, and merging between branches is simple.

Let's pretend you are going to make a fairly major change, the implementation of a new subsystem. This is going to take you awhile, and you don't necessarily want to impede everyone else's work while you are doing it. It's also nice to be able to version your work so if something goes awry you don't lose everything. This is like what we did with the "X CHECKPOINT" commits in CVS before. In git you would instead create a branch for your work and merge from your branch into master when you have something you want to share. When your work is completed (or you decide it's a bad idea and you want to start over) you can destroy the branch. You can also switch between branches at any point. If you are working on subsystem X and someone finds a bug in subsystem Y that you want to fix, you can switch back to master and make a fix without disturbing your branch work. If you push your branch to the server, other people can work on your branch with you the same way as master.

To make a new branch, the command is "git checkout -b (name)", where (name) is whatever you want to call the branch. Generally the branch should be named for the issue/feature it is concerned with. Committing in your branch works identically to the master branch procedure described above.

To switch back to the master branch, do "git checkout master". Your working directory will be reset to the last commit. If you do this with uncommitted changes, your changes are lost. I assume you are warned about this, but I haven't tried yet. Changing back to your branch (or someone else's branch) is the same, "git checkout (name)".

When you have commited changes to your branch and want to merge your changes into master, switch to the master branch do "git merge (name)". This does not affect work on the branch, it can continue. Bringing changes from master into your branch works the same way, do "git merge master" with your branch active. Generally you do not have to do this unless further work in your branch needs the work done in master. Since you don't have to continually worry about other peoples' changes, your work in your branch is less interrupted. Conflicts in branch merging are handled as they are in commit. Resolve the conflicting blocks in VS and commit when completed.

Pushing and fetching changes to the rest of the world works as described with the master branch instructions, just provide the branch name in place of "master".

When you have completed work on your branch and merged its changes into master, the command to delete it is "git branch -d (name)". Once that is done you can delete the branch from the main repository by doing "git push origin :(name)". Note the colon before the name - this is the signal to delete the branch.
« Last Edit: August 05, 2015, 04:03:04 AM by dseagrav » Logged
pattersoncr
Project Team Member
Full Member
****
Posts: 212


View Profile Email
« Reply #3 on: August 19, 2015, 05:49:18 PM »

What do those of us who will not be doing any coding need to do to keep current with the latest version?
Logged
dseagrav
Project Admin
Hero Member
*****
Posts: 1118


View Profile
« Reply #4 on: August 20, 2015, 12:21:53 AM »

What do those of us who will not be doing any coding need to do to keep current with the latest version?

Follow the steps in the first post to get a tree, then just do a fetch/merge and recompile when you want to update. Since you never make any changes there should never be any conflicts. If you want to follow a feature branch instead of master, checkout the branch you want and merge from that instead of master. If you somehow make a big mess and need to reset the tree, do "git reset --hard HEAD^"

Logged
indy91
Hero Member
*****
Posts: 1316


View Profile
« Reply #5 on: October 03, 2016, 09:54:37 AM »

WORKING WITH FORKS AND PULL REQUESTS:

If you have not been added as a contributor to the NASSP repository, you can still contribute to the project. So here a short explanation how to set up a NASSP fork, how to put your changes on Github and how to do a pull request, to get the changes in your fork into the main NASSP repository.

I am using a weird mixture of git bash and git gui. Git gui to have an overview of my changes and to stage and commit them, and git bash for pushing changes and fetching the remote repositories. Everything I will explain here can be done exclusively with Git GUI or Git Bash, I think.

First you will have to create a fork of NASSP on Github. There should be a button for that here: https://github.com/dseagrav/NASSP Next open git bash and cd to where you have Orbiter for NASSP installed. If you are starting from scratch, so you don't have NASSP set up with git yet, then you can use the same names for the remote repositories as I will use here. You can use steps 1-8 from the first post in this thread, but instead of using origin for dseagrav/NASSP you should set it up to link to your fork. So basically:

5) Type "git remote add origin https://github.com/yourusername/NASSP.git"

But you can also name the remote "fork" or anything you want. When you are finished setting up your local repository, then set up the remote for the main repository next:

-"git remote add upstream https://github.com/dseagrav/NASSP.git". Now your local repository knows both about the main NASSP repository and your fork.
-"git fetch upstream" to download the data from the main repository.
-"git checkout master" to change to your local master branch, if that hasn't already been done.
-"git merge upstream/master" to merge the changes of the main repository master branch into your local copy. If you have just done the fork, then there shouldn't be any differences yet.

At this time you should be doing the changes you want to integrate in NASSP. When you are finished with them open Git GUI. You might need to set it up, so that it links to your NASSP repository. You should now have unstaged changes. Choose the file(s) and press "Ctrl+T" or use the dropdown menu for the "stage to commit" command. Do this with all the files you want to commit. Now write a nice and short commit message in the window for it. Then press commit. Now your local changes have been commited to your local master branch of the fork repository.

I am doing the pushing in git bash, so type "git push origin master" to push your local changes to the remote fork repository on github. If you go to Github now, you will see the changes you have made. It will probably also say "This branch is 1 commit ahead of dseagrav:master" or something like that.

Next is the pull request. This might be a little bit annoying to set up on Github. Go to https://github.com/dseagrav/NASSP/pulls and press "New pull request". On the compare page, choose "compare across forks". There you have to use the drop down menues to setup up the base fork as "dseagrav/NASSP" and the head fork as "username/NASSP". In the end the line of drop down menus should say: "base fork: dseagrav/NASSP base: master ... head fork: username/NASSP compare: master". Type a title and description for your pull request and allow edits from maintainers. If everything is ready, then press create pull request. Don't worry about breaking anything, a pull request is just a request. Now we can all have a nice discussion if the pull request is any good.

If yes and when the pull request has been merged, you need to let your local repository know about it.

-"git fetch upstream" to download the data from the main repository again.
-"git checkout master" to change to your local master branch again.
-"git merge upstream/master" to merge the changes of the main repository master branch into your local copy. It will probably say something about "fast forward", because there are actually no differences between the main and fork repositories, just the merge commit in the main repository.

This has been written for changes with the master branch, but if you want to contribute to any other branch (e.g. the one for Orbiter 2016) then it works the same way, just with a different branch name. If you are not doing any regular development, then you use the three commands above to get the up-to-date changes to the master branch of the main repository in your local copy.

« Last Edit: October 18, 2016, 12:20:02 PM by indy91 » Logged
kneecaps
Project Team Member
Full Member
****
Posts: 217


36711000 kneecaps@shockpulse.co.uk
View Profile
« Reply #6 on: October 04, 2016, 05:17:40 PM »

I would suggest that even if you can commit to the master branch directly, that we never do that. Best practice in the industry is to do all work on a branch and then merge it via a pull request. This keeps things very clean and tidy.
Logged

"Okay. As soon as we find the Earth, we will do it."
- Frank Borman, Apollo 8

Current Work: ?? What next??

Future Work:
I know the AGC pretty well so anything need doing there?

On Hold/Completed:
SPS TVC in P40 issues.
P11 FDAI Error Needles (98%) complete. Comitted. Working A7 scenario.
P06 AGC Standby. Concluded. It's done by the AGC PSU.
Got us a complete AOH Volume II
dseagrav
Project Admin
Hero Member
*****
Posts: 1118


View Profile
« Reply #7 on: October 07, 2016, 12:37:30 PM »

Yeah, but then the auto builder isn't available until merge time, which makes incremental testing harder. That's specific to us though.
Logged
Pages: [1] Print 
« previous next »
Jump to:  

Powered by MySQL Powered by PHP Powered by SMF 1.1.10 | SMF © 2006-2009, Simple Machines LLC Valid XHTML 1.0! Valid CSS!