Magic Lantern Forum

Developing Magic Lantern => General Development => Topic started by: dfort on April 09, 2019, 11:56:44 PM

Title: Bitbucket for Beginners
Post by: dfort 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 (https://bitbucket.org):

(https://live.staticflickr.com/7850/47573885911_633a2f42b0.jpg) (https://flic.kr/p/2ftWAQg)

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 (https://confluence.atlassian.com/bitbucketserver/bitbucket-server-documentation-776639749.html) 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:

(https://live.staticflickr.com/7820/33696923808_3ddb673c7d.jpg) (https://flic.kr/p/TkFxsY)

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:

(https://live.staticflickr.com/7920/33696924118_ee36c39229.jpg) (https://flic.kr/p/TkFxyj)

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:

(https://live.staticflickr.com/7894/47520924232_0756828ba5.jpg) (https://flic.kr/p/2fpgaaS)

(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:

(https://live.staticflickr.com/7853/47520924422_e38e9d59d1.jpg) (https://flic.kr/p/2fpgae9)

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

(https://live.staticflickr.com/7903/33696924188_6dd0551a7e.jpg) (https://flic.kr/p/TkFxzw)

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) (https://www.mercurial-scm.org/) either in a terminal or in a GUI front end like Sourcetree App (https://www.sourcetreeapp.com/) or TortiseGit (https://tortoisegit.org/) or even Danne's Compiler.app (https://www.magiclantern.fm/forum/index.php?topic=21882.0) 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:

(https://live.staticflickr.com/7833/33696923938_6ed5e97135.jpg) (https://flic.kr/p/TkFxvd)

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.

(https://live.staticflickr.com/7858/47520924332_e617fe1fa9.jpg) (https://flic.kr/p/2fpgacA)

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.

(https://live.staticflickr.com/7879/33696924038_448dde6e2a.jpg) (https://flic.kr/p/TkFxwW)

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.
Title: Re: Bitbucket for Beginners
Post by: calle2010 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.
Title: Re: Bitbucket for Beginners
Post by: calle2010 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.
(https://i.ibb.co/wCdPRkr/2-BCC212-F-C862-4964-A674-17-E4398-AFCE1.jpg) (https://ibb.co/wCdPRkr)

Title: Re: Bitbucket for Beginners
Post by: dfort 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.
Title: Re: Bitbucket for Beginners
Post by: scrax on June 17, 2019, 04:05:12 PM
Is just me, or there are problems with pull request on bitbucket site?
I can't see none...


EDIT: MAybe bitbucket problem, I can go to a specific pull request with direct link but the list is empty for open, merged, or closed PR
Title: Re: Bitbucket for Beginners
Post by: critix on July 04, 2019, 12:27:32 PM
Congratulations for the tutorial.
Even though I have been working for a while (not much) with bitbuchet, I still have to learn about bitbuchet ...
Title: Re: Bitbucket for Beginners
Post by: timbytheriver on December 05, 2019, 03:09:13 PM
I have cloned one of @Danne's builds to start working on files locally. Now I want to share my code on a repo I create on Bitbucket, but I doubt very much my code will ever be merged into Danne's or the main ML repo. For the moment I simply want to push my changes to my online repo to share: My local > My online repo.

Don't want to eff-up and accidentally wipe someone's life's work!   :o

What should I do?

Many thanks!
Title: Re: Bitbucket for Beginners
Post by: names_are_hard on December 05, 2019, 04:38:21 PM
First - don't worry!  You can't delete someone else's code.  They would need to configure their repo so your user could write to it.  The default is "everyone can read, only the owner can write".  Even if you *did* make changes, which you can't, Bitbucket allows people to undo changes.  You can change your own repo however you like.

There are many ways to upload your changes.  Do you prefer GUI or CLI?  Did you choose Git or Mercurial on Bitbucket?
Title: Re: Bitbucket for Beginners
Post by: timbytheriver on December 05, 2019, 04:53:59 PM
Thanks again. Reassured! :)

I understand Mecurial is being stopped in Bitbucket soon. But I have no Git experience, and only a little Mecurial. What do you suggest?

I have Sourcetree GUI installed.
Title: Re: Bitbucket for Beginners
Post by: names_are_hard on December 05, 2019, 05:20:26 PM
Git and Mercurial do the same things, in similar ways.  The ML devs bet on the wrong horse, Git won, Mercurial lost.  There's no future for Mercurial.  However, if you only ever want to work on Magic Lantern, it will be easier to use Mercurial.  When Bitbucket removes Mercurial support, ML will probably move to some other provider of Mercurial (that will probably die a few years later on).

If you choose Git you'll learn a tool that's more generally useful (simply because 99% of people use Git, not because Git is better or worse than Mercurial).  But, you'll have to run some extra commands whenever you want to share code from your repo to ML repo, or vice versa.  Given you are learning a lot of confusing things at the same time, this may not be the best option :)

Git and Mercurial use similar words to mean different things.  This is often very confusing (and led to me deleting my code multiple times trying to use Mercurial for ML, so I'm sticking with Git).  When you search for tutorials make sure it's the right flavour.  Most tutorials will be Git, because nobody uses Mercurial.

Apparently Sourcetree work with both flavours, so that's good.  Dfort's instructions in this thread tell you how to use the Bitbucket web interface to talk between your fork and the main ML repo.  So, if you configure Sourcetree to only work on your repo, you can use Sourcetree for your changes, then if you ever want to put things from there into ML, you can use Bitbucket for that half.  In other words, don't worry about it yet; use Sourcetree for your local work and save the rest for the future :)
Title: Re: Bitbucket for Beginners
Post by: timbytheriver on December 05, 2019, 07:33:23 PM
Thanks plenty. Great advice. :)
Title: Re: Bitbucket for Beginners
Post by: timbytheriver on December 11, 2019, 11:08:45 AM
Read the above OP's tutorial but I think I've already deviated from the path described and am a bit lost!

I started originally by cloning one [Danne's] repo onto my local machine. Made some code changes locally. Then I pushed that to my remote repo.

Now Danne's repo has been updated, and I want to merge his new changes into my repo – but not overwrite my changes. I can't see how I would do this other than manually compare files side by side...  :o

Any tips pls?



Title: Re: Bitbucket for Beginners
Post by: Danne on December 11, 2019, 11:13:50 AM
Redownload a fresh version of my branch or update my branch in your source tree. Then either manually add my latest commits into your ongoing branch or create a new branch with my latest changes and add in your own stuff into that one.
There´s probably more ways of doing this...
Title: Re: Bitbucket for Beginners
Post by: names_are_hard on December 11, 2019, 02:24:04 PM
Tim - the search term you want is "merge tool".
Title: Re: Bitbucket for Beginners
Post by: timbytheriver on December 11, 2019, 05:23:42 PM
Great. Ta!