Author Topic: Bitbucket for Beginners  (Read 269 times)

dfort

  • Developer
  • Hero Member
  • *****
  • Posts: 3651
Bitbucket for Beginners
« on: April 09, 2019, 11:56:44 PM »
Bitbucket for Beginners

Several ML users have followed the compiling tutorials and have started making modifications to the code. Great! That's encouraged. However, in some cases those changes stay on the user's hard drive and the changes aren't being shared. In some cases snippets are posted in the forum or entire repositories zipped up and placed on Google drives. Sharing your changes the right way isn't difficult. In fact you can do it easily using the web user interface in Bitbucket. Let's get started.

Start by creating a free account on Bitbucket:


Bitbucket is the web server front end that can be used for GIT and Mercurial software versioning and revision control system. There's plenty of online documentation but let's skip the instructions and get started.

Go to the main Magic Lantern repository at: https://bitbucket.org/hudson/magic-lantern

It will start on the source page and if you scroll down you'll see the README file:


The first thing you want to do is to fork this repository. On the left side of the web page there is a "+" sign -- click it. The option to Fork is at the bottom:


When it gives you the option to name it, just keep the default name -- Magic Lantern. Some users have lots of forks, one for each branch but that isn't necessary. In fact there is little reason to create another fork.

Some people haven't gotten past this step. They fork the main repository and there it sits quickly going out of date as commits are pushed to the main repository. Yet it is so easy to update your fork. On the right side of the web interface there is a button to sync your fork:


(Of course my fork isn't really that far behind, I tricked it for illustration purposes.)

Ok--so let's say you are working locally and made some changes that you'd like to share. It doesn't really matter how you worked on your local repository but let's keep things neat and orderly on the fork which brings up rule number one -- Make a branch that has a name that isn't being used on a branch in the main repository. The reason for this is that Bitbucket will not sync your fork if there have been changes to the same branch on both your fork and the main repository. Making a new branch on your fork is easy:


Next decide where you are branching from and what to name your new branch:


Ok--so let's say you've been hacking away and you almost have something good enough to share -- share it! Don't hold back until you are finished and are 100% satisfied. Of course whatever you share should be in somewhat working order and won't brick the camera.

Now how do you get it from your text editor to the cloud? The main repository and your fork are using a software versioning and revision control system called Mercurial so ideally you should be using Mercurial (hg) either in a terminal or in a GUI front end like Sourcetree App or TortiseGit or even Danne's Compiler.app but this topic is about just using the Bitbucket web interface so let's edit the source code online.

Making sure you're on the right branch, open the file you want to edit and simply press the Edit button on the upper right corner of the frame:


This should be familiar to anyone who has edited anything online or posted on a forum. Shortcut, simply copy from your text editor and paste to the edit window and you're done. Commit your changes making sure your commit message makes sense to someone else. Too many online edits end up with a commit message that says, "edited online with Bitbucket" which isn't very helpful.

Now what happens when you sync your fork and discover that the file you're working on was updated on the main repository? You can merge in those changes into your working branch.


Make sure you're going the right direction or you'll end up making changes on the wrong branch. If you want to preview the merge you can create a pull request. This will also allow you to see if there are any conflicts between the changes you made and the changes made on the main repository.


Speaking of pull requests, once you do have something you'd like to contribute you can easily make a pull request from your fork to the main repository.

Of course there's a whole lot more that you can do in Bitbucket but this is just an introductory tutorial.

One more point, don't be afraid of messing things up. If things get too confusing simply delete your fork and start over. When I first started I must have made a dozen forks--and re-cloned to my hard drive maybe a hundred times.
5D3.* 7D.206 700D.115 EOSM.203 EOSM2.103 M50.102

calle2010

  • Contributor
  • New to the forum
  • *****
  • Posts: 46
Re: Bitbucket for Beginners
« Reply #1 on: April 10, 2019, 07:15:15 AM »
Thank you for the tutorial. This should be a sticky.

On good commit messages: https://medium.com/compass-true-north/writing-good-commit-messages-fc33af9d6321

Or simply read commits made by Alex (always something to learn) and take note how he uses commit messages.

calle2010

  • Contributor
  • New to the forum
  • *****
  • Posts: 46
Re: Bitbucket for Beginners
« Reply #2 on: April 10, 2019, 07:22:36 AM »
To merely compare branches you don't need to create a Pull Request (PR) and potentially annoy the upstream repository owner. In the branches view you can select a branch and select compare. The functionality is very similar to creating a PR, without actually doing it.



dfort

  • Developer
  • Hero Member
  • *****
  • Posts: 3651
Re: Bitbucket for Beginners
« Reply #3 on: April 10, 2019, 08:48:26 PM »
Good point.

What I was suggesting was doing a pull request on your fork. This is something that a1ex does quite a bit on the main repository. It is useful for keeping track of the changes that it will make when you merge. It is also good practice to do a "fake" pull request on your fork before attempting it on the upstream repository.

Note that I just discovered that due to some changes in the UI, the fork syncing feature isn't currently working. Hopefully they will figure this out soon because that is a very handy feature, especially if you want to do as much as possible using just your browser.
5D3.* 7D.206 700D.115 EOSM.203 EOSM2.103 M50.102