How-To GIT with Keystone

[Carlos Colon]

I'm fairly new to GIT and have not been able to establish a proper procedure for contributions, which I like to do.  I have forked the master branch onto https://github.com/webteckie/keystone, I have cloned that to a local repository in my PC and now is where my misunderstanding starts.  I like to ask some specific questions and hopefully I learn here enough GIT by example for successful contributions to the project.  With that said, what is the correct process to:

1) First to make sure I have a clean repository to make my changes on, what are the series of steps / commands to make sure that my forked and local copy are in sync with the master?  Assume I have no changes to commit and I just want to be in sync with master.

2) Now that I have a clean repository, I like to make some changes to my local copy.  I know how to work with local branches and commits but it want to mention steps for the benefit of others feel free.  But my specific question here is that I like my project's Packages.json to use my local copy for local testing.  How do I configure the local copy in my Packages.json file?  Currently I'm directly pointing to Master as follows:  "keystone": "git://github.com/JedWatson/keystone.git"

3) ok, so now I've made local changes, tested them in my project, and now I like to push this to my fork and then master?  What are the best series of commands / steps to accomplish this?

I think once I know how to do all 3 steps above I should be all set.  Hopefully, the answers will also help some folks that are newer go GIT as well and we can all start more quickly contributing :-)

Thanks

Carlos

PS:  I have read some on similar threads but they all say different things and I get a little confused.  So hopefully having concrete steps specific to Keystone will help me better understand!

[Stennie]

On Monday, 2 June 2014 01:23:56 UTC+10, Carlos Colon wrote:

I'm fairly new to GIT and have not been able to establish a proper procedure for contributions, which I like to do.  I have forked the master branch onto https://github.com/webteckie/keystone, I have cloned that to a local repository in my PC and now is where my misunderstanding starts.  I like to ask some specific questions and hopefully I learn here enough GIT by example for successful contributions to the project.

Hi Carlos,

Git allows multiple workflows depending on your preferences, so I wouldn't say there is any One True Path however I've found the following Works For Me ;-).

For general workflow I'd read:

 http://nvie.com/posts/a-successful-git-branching-model/

Github has a good guide for forking repos:

 https://help.github.com/articles/fork-a-repo

 

 With that said, what is the correct process to:

1) First to make sure I have a clean repository to make my changes on, what are the series of steps / commands to make sure that my forked and local copy are in sync with the master?  Assume I have no changes to commit and I just want to be in sync with master.

Assuming you've followed the Github forking guide and added the original keystone repo as the "upstream" remote repo, you can then periodically keep your forked master in sync with:

 git checkout master
 git pull --rebase upstream master

If you never plan on making changes to the master code, you could also just pull from the main repo instead of forking.

 

2) Now that I have a clean repository, I like to make some changes to my local copy.  I know how to work with local branches and commits but it want to mention steps for the benefit of others feel free.

Always do any changes in your forked repo on a branch - ideally on discrete branches related to an issue number so they can be easily merged.

 # Create and switch to a new branch
 git checkout -b issue-123

 # Switch to an existing branch
 git checkout issue-123

 

 But my specific question here is that I like my project's Packages.json to use my local copy for local testing.  How do I configure the local copy in my Packages.json file?  Currently I'm directly pointing to Master as follows:  "keystone": "git://github.com/JedWatson/keystone.git"

For local testing, you should be able to just "npm install" from your checkout/branch without changing the Packages.json file: https://www.npmjs.org/doc/cli/npm-install.html.

 # use local keystone working copy in a local project:
 cd ~/src/project/magic
 npm install ~/src/keystone

Alternatively, you can specify your (committed) fork changes as a dependency in your project's Package.json using a git url:

  "dependencies": {
    "keystone": "git://github.com/myrepo/keystone#branch",
  }

You can also use `npm link` to symlink your dev npm packages if you want to use work in progress rather than a specific release point.

3) ok, so now I've made local changes, tested them in my project, and now I like to push this to my fork and then master?  What are the best series of commands / steps to accomplish this?

Ideally you should have your own working branch (eg "develop") where you merge changes separate from master. Otherwise you will create conflicts when your master's history diverges from the upstream master.

I would:

 - commit your changes to the feature branch

 - push to github

 - submit a pull request (PR) to the upstream project (NB: assuming you have committed discrete changes to the branch, this should only include the changes related to a specific issue)

 - merge those changes into your local "develop" branch

 ... when the PR is merged, you'll pick these changes up in your master branch again

Cheers,

Stephen

[Carlos Colon]

Hi Stephen,

Thanks for your feedback and the links!  Really helped!  I think I got through the entire cycle and got my first Pull Request done ... whether it gets accepted or not that's a different issue :-)

Thanks

Carlos

[Stennie]

On Tuesday, 3 June 2014 13:30:53 UTC+10, Carlos Colon wrote:

Thanks for your feedback and the links!  Really helped!  I think I got through the entire cycle and got my first Pull Request done ... whether it gets accepted or not that's a different issue :-)

Hi Carlos,

Cool, glad that helped. It does take a bit to divine suitable git workflow and command incantations :).

One more documentation link that's useful for commits via Github (especially when your changes relate to an existing issue):
 https://github.com/blog/831-issues-2-0-the-next-generation

You can reference issues via the commit message (eg. "Fixes #401 .. ." + suitable description of changes) and that will link your commit to the upstream issue even if it's in your own fork (i.e. before you've submitted a PR).

FYI, normally a PR will create a new issue for review of the PR.

Cheers,
Stephen