AudioLibrary Github workflow

Status
Not open for further replies.

neurofun

Well-known member
Since I received my first ever Teensy, 6 weeks ago, I've been working quite a lot on the audio lib.
Without thinking too much I just copied the Audio folder from the ardiuno application to the libraries folder inside the sketch folder and started programming away.
So far I've fixed a few bugs and made about 6 new objects and then yesterday it hit me, trouble ahead at the next teensyduino update. I will probably have to manually merge the new audiolib with my existing one, bummer.

Github to the rescue?
What I understand so far, please correct me if wrong.

Login to my Github account.
Navigate to Pauls's Teensy Audio library page. https://github.com/PaulStoffregen/Audio
Click the "fork" button. Github redirects me to my own Teensy Audio library page.
Click "Clone or download" and select "Open in Desktop". Github Desktop (osx) opens and ask where to clone.
Select the libraries folder inside the sketch folder and click "clone".
I have now a local copy of "Audio" to work on.
Every time I am happy with my changes I click "commit to master" in Github Destop. This creates a "snapshot" of my progress on my local machine to which i can revert if necessary.
If I want to upload my local repository to Github, I go to the "Repository" menu in Github Desktop and select "Push". My remote repository is now an exact copy of the local one.

Now, Paul updates the audiolib on Github and i would like to merge the new lib with my local one.

Open terminal from Github Desktop and type:
git remote add upstream https://github.com/PaulStoffregen/Audio.git
git fetch upstream
git checkout master
git merge upstream/master

What does the "Update from PaulStoffregen/master" button do in Github Desktop, is it the same as above?

Now, what I don't understand yet.
Let's say I made 2 bug fixes and created 2 new objects and i want to make 2 separate pull requests, one for a bug fix and one for a new object.
Does it make a difference if those 4 changes were committed together or at 4 different times?
Is the point where branching comes into play?
In short, how is it done?

For the bug fix I know it might be easier to post a new issue on the Github page, just trying to wrap my head around all this new git stuff.
 
The best way is to fork the original repository, then create a branch in yours for each contribution. When you've made the commits on that branch and you've pushed them to github, then you can use github to send a pull request.

While nice, this really isn't necessary. It's perfectly fine to just post a zip file here with your modified copy of the library, and some description of what you've done.

Please understand I've become quite a bit more cautious about accepting audio contributions, after getting burned by some not-so-great code. Typically it can take a few months before I manage to find the time to really evaluate them. Remind me, but also know I'm juggling a lot of tasks.
 
I am no expert in git, but do try to make updates to some of the standard libraries. I have not done Audio in awhile, but do make some in other parts of the system like: core, SPI, usbhost_t36...

In several of these libraries, if I am doing a lot of stuff over time, I may have both my forked version and Paul's version on my local computer. Example, with cores.
I have my version cloned to: C:\Users\kurte\Documents\GitHub\cores
I have the original (Paul's) cloned to: C:\Users\kurte\Documents\GitHub\Master\cores
So I can use Github desktop to sync Paul's and see his later changes...

As Paul mentioned, if I am making changes, I create a new Branch in github desktop and save any of my changes back up to the new branch. When I am happy with them and would hope to get them incorporated into the master version I issue a Pull request.

If while doing this, I make a lot of smaller changes, and would like to cleanup my history of changes into a fewer set of changes (like 1), I merge my changes... Usually each time I do this, I do a search on the net.
And refresh myself how to do it, like looking at: https://github.com/todotxt/todo.txt...elated-to-a-Single-Issue-into-a-Single-Commit
Short version if you had 4 commits, you could use the HEAD~4... If different number of commits use different number... Then need to force changes back to github...
Code:
git rebase -i HEAD~4
git push origin branch-name --force

When I wish to git the master branch of my fork up to date with Paul's version, I use a sledge hammer approach and have a batch file I have setup to do it. BUT WARNING: if you have local changes that have not been saved, you can lose them with this approach as I use force... Example batch file for cores;
Code:
cd \Users\kurte\documents\GitHub\Cores
git fetch upstream
git checkout master
git reset --hard upstream/master
git push origin master --force
cd %home%

This works similar to what you mentioned and like the "Update from... " button you mentioned. What I don't like about the update button, is it does sync all of the latest changes, but then also adds another entry to the github log, showing you did the update just then... Which is fine, but I have had issues where then trying to merge into other branches or to create Pull requests that there are now conflicts... So I keep using the hammer.

Now if I want to update my Branch to have Paul's latest stuff in it, I first scared and make a copy of my current stuff to another folder :D Then I look it up again and find websites like: https://stackoverflow.com/questions/5340724/get-changes-from-master-into-branch-in-git/5340774

After that I do the thing to get my master up to sync with Pauls. I then in command window do something like:
Code:
git checkout mybranch  (Or I already do this in github desktop)
git rebase master
As part of this I may need to fix any conflicts, once that is all done, may need to push updated version back up to github (probably needing force)... Also don't remember if this added a new history item into github.... If it does, I use the git rebase -i... stuff above to shrink that back down...

Again I am no expert, but hope that helps
 
It's perfectly fine to just post a zip file here with your modified copy of the library, and some description of what you've done.

Please understand I've become quite a bit more cautious about accepting audio contributions, after getting burned by some not-so-great code.

That's what i'll do until I become more proficient with git.
You being more cautious about accepting audio contributions is actually quite reassuring.
Without elaborating too much could you maybe point out a few dos and don'ts for avoiding not-so-great code?

Again I am no expert, but hope that helps

Oh yes, you were of great help. I'll still have to read your post and the links a few more times before I get the gist of it.
The good thing is the audio lib was just updated with the AudioOutputADAT object so now I can try everything out.
 
Without elaborating too much could you maybe point out a few dos and don'ts for avoiding not-so-great code?

The public API is the most critical part for acceptance into the library. Programming mistakes and poorly/partially implemented features can be fixed later, but altering public functions after people have used them in their programs is painful.

Likewise, some ideas are a very natural fit into the library, others can seem pretty redundant. The list of objects in the design tool is already pretty long, and many more are planned. If you have specific features in mind, they might belong as their own objects, or they might "fit" best into the larger system in the long-term as extra options in existing objects. My long term goal is to only grow the list of objects when necessary. I believe in github's zen "anything added dilutes everything else" philosophy. If the proposal adds a new object, it needs to be worth the extra cognitive load that will forever impose on all users to look at such a long list and understand the library as a whole.

For posting code here, or on a github fork, I'd say don't be shy. Better to share and talk early.

On the "Do" side, try to come up with a couple compelling example programs. The ideal is one very simple program to demonstrate how to use it without reading a lot of extra code, and one really awesome program that demonstrates what your new feature can really do when put to good use together with other stuff from the library.

The main "Don't" is leaking memory. It happens. I've done it. But do try to keep your code simple if you can, and if you do have numerous flow control paths, every audio block you allocate or receive must be released in every possible path.
 
Status
Not open for further replies.
Back
Top