Hi Michael, This is not a GitHub thing ... it's the git way of doing (somewhat) centralised development with a de-centralised version control system.
To git every repository is equal. If we assign more importance to one repo(sitory) than another it is by convention only. Period. Now if a couple of people work together they could conceivably all have their own version of the product and only pull changes from others as they see fit. Git would support that 100%. The problem is that, as the product evolves (grows), it takes more and more effort to keep in sync for the features/fixes you want. In real life, it's often more practical to agree on one source repo as a reference ... and then make changes relative to that. You can still have your own version (branch, fork, whatever) but you would be moving alongside this agreed central reference. Take Linux as an example. The rep Linus Torvalds maintains is, from a git point of view, no better than anybody else's. However, since most people agree he's doing a great job at nurturing Linux and integrating changes (almost) everybody is using it as a reference and uses it's version count for starters. This central repo is what we call "upstream". In case of OpenXPKI, it's openxpki/openxpki on GitHub. No (GitHub) magic involved. Does that clarify things? Or am I completely off? Kind regards Andreas -- Andreas Leibl, RSTC Ltd Registered in England no: 6306790 VAT Registration no: 901 2682 54 Registered Office address: 38 Lambourne Way, Bristol, BS20 7LQ, United Kingdom On 15 Apr 2012, at 17:58, Michael Bell wrote: > Hi Andreas, > > github.com uses a remote repo called upstream. The primer document does > not describe the usage of such a repository. > > So if I understand the beginner documentation on github.com correctly > then the changes to upstream are never visible in the forked repo. So I > think that the described developer workflow brings the forked repo > permanently out of sync with openxpki/openxpki. > > Is my understanding of git correct here? > > Best regards > > Michael > > > Am 02.04.2012 10:43, schrieb Andreas Leibl: >> Dear all, >> >> Changing the version control tool for a project is never easy and I want >> to say a big thank-you to all the developers that weren't git users >> before and still agreed to the move ... it can be daunting at times. >> Following some remarks and issues on this mailing list I'd like to >> provide a little write-up that should help everyone get going without >> spending too much time learning git. >> >> For those inclined to dig deeper into git there are lots of tutorials on >> the web but I'd also like to recommend the following O'Reilly book and >> videos to you (they helped me a lot on the way): >> >> http://shop.oreilly.com/product/0636920022862.do >> http://shop.oreilly.com/product/0636920017462.do >> http://shop.oreilly.com/product/0636920024774.do >> >> Now, without further ado, the promised primer. This is my understanding >> of how we want to do things, please correct me if I got it wrong. Hope >> you find it useful. >> >> Kind regards >> >> Andreas >> >> P.S.: I've added the primer to the repo. Can someone please have a look >> at the pull request? >> >> >> >> Git and OpenXPK ... a short primer for people new to git >> ======================================================== >> >> Introduction >> ------------ >> >> Some background info first, then onto the command line. OpenXPKI is >> based on UNIX so familiarity with the shell (korn, bash, ...) and SSH is >> expected. >> >> Authoritative repository >> ------------------------ >> >> https://github.com/openxpki/openxpki >> >> Register (for free) at github.com <http://github.com> and follow this >> project. The website will provide the URLs needed to perform a git clone >> (see below). >> >> Development model >> ----------------- >> >> Git does not force you to do things in a certain way. That's good >> because you can do things your own way. It's also bad because if >> different contributors use different approaches there will be chaos. >> >> There are two official branches: >> >> master The stable, production branch containing officially-released >> versions >> develop The unstable, development branch that may or may not work >> >> Additional branches may be created by integrators (see below for a >> definition of what an integrator is). >> >> If you want the code for the latest (or any) release: checkout the >> master branch. >> >> If you want to do the latest development build: checkout the develop branch. >> >> For some philosophical insight into the branching and naming philosophy >> used here please see git-flow (https://github.com/nvie/gitflow) >> >> Roles >> ----- >> >> Note: any person can have more than one role, i.e. act as both an >> integrator and developer. >> >> - Integrator: >> An integrator's job is to take code provided by developers and integrate >> it into other branches. In this role (s)he does not write any code but >> simply puts things together. Integrators have write access to the >> authoritative repository. >> >> - Developer: >> Writes/changes code and pass them on to the integrators. They do not >> need access to the authoritative repository. >> >> >> Before we get started >> --------------------- >> >> >> Workflow for followers >> ---------------------- >> >> If you just want to follow the project (e.g. to do stable and >> development builds) you can pull directly from the authoritative repository. >> >> git clone git://github.com/openxpki/openxpki.git >> >> To follow the official releases, do >> >> git checkout master >> >> and then >> >> git pull >> >> whenever you want to update your local copy. >> >> To follow the (unstable) development (e.g. for your nightly builds), do >> >> git checkout develop >> >> and then >> >> git pull >> >> whenever you want to update your local copy. >> >> >> >> Workflow for developers >> ----------------------- >> >> Note: There is more than one way to do it. This describes the workflow >> based on GitHub's pull request feature. Using this feature is not a >> requirement, so if you're familiar with git feel free to do it your own way. >> >> First, you need to create your own repository on GitHub. >> >> - Login to GitHub. >> - Go to https://github.com/openxpki/openxpki and click on "Fork" on the >> upper right hand side. This will create your own, public repository >> based on the official one. Click on "Fork to <your username>". >> >> Next, you need your own local copy of that repository. >> >> git clone [email protected]:<username>/openxpki.git >> cd openxpki (the newly created directory containing your copy) >> >> Work is performed in your own, private branches, which are based on the >> develop branch. An integrator will integrate your work into the develop >> branch later after you've finished your piece of work. >> >> - Switch to the development branch: >> >> git checkout develop >> >> - Important: create your own branch, e.g. "feature/git-primer" >> >> git branch feature/git-primer >> >> - Important: switch to your new branch: >> >> git checkout feature/git-primer >> >> - Important: push your new branch to your own GitHub repository >> >> git push origin feature/git-primer >> >> Code ... (or write documentation ... or both). >> >> After completing a meaningful piece of work you may want to commit your >> changes to your private branch. >> >> - To remove files, use git rm file(s). >> - To add new files in the next commit, use git add file(s). >> - To stage modified files for the next commit, use git add file(s). >> >> Files you have created or modified but not staged using "git add" will >> not be committed. Now use >> >> git commit >> >> to commit the staged changes. The format of the log message should be: >> >> - One line containing a brief summary of the commit. >> - A blank line. >> - Further explanations of the commit if necessary. >> >> Whenever you want others to see the work you are doing in your own >> branch you can push your commits to your own GitHub repo using >> >> git push >> >> Your work is happening on a separate branch, so it is not affected by >> any commits to the master or develop branch. Hence it is safe to do regular >> >> git pull >> >> requests to stay in sync with the upstream repo. >> >> Let's say you created your own feature branch when the develop branch >> was as commit b and you created your first commit x: >> >> develop a - b >> \ >> feature/git-primer - x >> >> Now someone else's changes may get added to develop and your changes are >> no longer based on the latest commit of the develop branch: >> >> develop a - b - c - d >> \ >> feature/git-primer - x >> >> This may or may not create problems when integrating your changes into >> the develop branch. To facilitate integration, you should make sure that >> your changes are based on the latest commit of the develop branch before >> sending a pull request. This is done by rebasing your commits (sometimes >> also referred to as rewriting history). >> >> If your work does not conflict with the changes in develop (i.e. you >> haven't changed the same lines) the command >> >> git rebase develop feature/git-primer >> >> will result in a new graph like this: >> >> develop a - b - c - d >> \ >> feature/git-primer - x' >> >> Note: if "git rebase" does result in conflicts you will need to resolve >> these before you can proceed. Ask your friendly git guru for help if >> necessary. :-) >> >> Note: if you have "git push"-ed your previous commits to your GitHub >> repository your local copy and the one on GitHub will have diverged. To >> fix that, you will need to >> >> git push -f >> >> once to force your local changes into (your own) GitHub repo. >> >> Let's say you complete your work with one final commit >> >> develop a - b - c - d >> \ >> feature/git-primer - x' - y >> >> and pushed everything to GitHub. You can now ask an integrator to pull >> your changes into the develop branch. >> >> To do that, log on to GtHub and visit your own openxpki repo fork. >> >> - Click on the branches tab. >> - Click on your branch that you want merged upstream. >> - Click on "Pull Request" in the upper right hand corner. >> >> IMPORTANT: make sure you adjust the settings on the following screen. By >> default, it will suggest merging into the master branch. Change this to >> the develop branch and click on "Update commit range". >> >> Click on "Send pull request". >> >> A few final notes: >> >> - You can have (and work on) as many private branches as you like. >> - For different features or bug fixes create different branches. >> - If in doubt, branch. You can easily merge later. Splitting up commits >> is much more difficult. >> >> >> Workflow for integrators >> ------------------------ >> >> The job of an integrator is to act as a gatekeeper and quality assurance >> for changes to the project. When a developer sends a merge request all >> integrators will recieve a message. One of them will review the changes >> and either >> >> - accept the changes and merge the pull request or >> - write comments and ask for further information and/or changes or >> - decline and close the pull request without merging. >> >> Note: the integrator may be the same person as the developer that sent >> the pull request. >> >> To act on pull requests simply log on to GitHub and click on the pull >> request in your "Public Activity" timeline. If you can't find it there >> look at your notifications (the little radio tower at the top right). >> The web form is pretty self-explanatory. >> >> >> Famous last words >> ----------------- >> >> If you feel something is incorrect or missing in the guide ... please >> fork, branch, push and send a pull request. Thank you! :-) >> >> >> >> >> >> -- >> Andreas Leibl, RSTC Ltd >> Registered in England no: 6306790 >> VAT Registration no: 901 2682 54 >> Registered Office address: 38 Lambourne Way, Bristol, BS20 7LQ, United >> Kingdom >> >> >> >> >> >> This body part will be downloaded on demand. >> >> >> >> This body part will be downloaded on demand. > > > -- > ___________________________________________________________________ > > Michael Bell Humboldt-Universitaet zu Berlin > > Tel.: +49 (0)30-2093 70143 ZE Computer- und Medienservice > Fax: +49 (0)30-2093 70135 Unter den Linden 6 > [email protected] D-10099 Berlin > ___________________________________________________________________ > > PGP Fingerprint: 09E4 3D29 4156 2774 0F2C C643 D8BD 1918 2030 5AAB > > ------------------------------------------------------------------------------ > For Developers, A Lot Can Happen In A Second. > Boundary is the first to Know...and Tell You. > Monitor Your Applications in Ultra-Fine Resolution. Try it FREE! > http://p.sf.net/sfu/Boundary-d2dvs2_______________________________________________ > OpenXPKI-devel mailing list > [email protected] > https://lists.sourceforge.net/lists/listinfo/openxpki-devel ------------------------------------------------------------------------------ For Developers, A Lot Can Happen In A Second. Boundary is the first to Know...and Tell You. Monitor Your Applications in Ultra-Fine Resolution. Try it FREE! http://p.sf.net/sfu/Boundary-d2dvs2 _______________________________________________ OpenXPKI-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/openxpki-devel
