Confusing terminology in "02. First Steps" of Tutorial "Getting Started With SuperCollider"

[afischli]

On a Mac the keys 'Enter' and 'Return' are not the same and should not be confounded. The current tutorial text in "02. First Steps" of Tutorial "Getting Started With SuperCollider" (version 3.7alpha1) is therefore quite confusing on a Mac, since it confounds those two keys. The sentence "To execute it, simply click to place the cursor somewhere on the same line as the code and then press Ctrl-Enter (Cmd-Enter on the Mac) or Shift-Enter. Try this now." needs therefore to be rewritten. I suggest following text: "To execute it, simply click to place the cursor somewhere on the same line as the code and then press Ctrl-Enter (Cmd-Return on the Mac) or Shift-Enter (Shift-Return on the Mac). Try this now.". Otherwise a user has a hell of a time to get 'Hello World!' running. I tried several keyboards, tried to enter the command into another window etc. before it occurred to me that the tutorial text merely uses a wrong terminology.

[afischli]

Another 2nd issue I take with the 2nd example. Again two concepts are confounded here, i.e. that of a terminal symbol and that of a separator. Since the semi-colon is sort of a separator, you need to explain why you may have a semi-colon at the very end or have also the freedom to leave it out. I suggest to add following text after "...between the two lines we would get an error.": "Having an extra semi-colon at the very end does not hurt and is tolerated for reasons of convenience.".

Rationale: Since empty statements are not tolerated by SC, (';;' leads to a parser error) and having a semi-colon at the very end where no further statement follows unless you would assume an empty statement, the semi-colon is not a proper statement separator. Note, it is also not a proper line terminator, since a construct such as '"Hello World!".postln;"Hello SC!".postln' is parsed correctly. Thus the semi-colon has indeed some separation function. The actual problem comes of course from poor language design as is unfortunately quite common in C influenced programming languages. So things get unnecessarily complicated and leave the beginner's understanding in a foggy state of not being sure what the role of a semi-colon really is, since it is neither a true statement separator nor a true statement terminator.

[afischli]

A 3rd issue is with the sentence "This is convenient as it allows you to select the whole block of code by double clicking just inside one of the parentheses." This does not work as described on a Mac. The selection result of a double click depends on the context of where you set the cursor. With default systems settings double-clicking In the middle of a word selects just that word. Only double-clicking near the parentheses, e.g. on the line of the first or last parenthesis, allows me on my system to select the entire construct as intended.

Fix: Enhance following text at the end of the confusing sentence so that it reads: "You can have your cursor anywhere in this region (or on the line of the parentheses on the Mac) and press Ctrl-Enter (Cmd-Return or Shift-Return on the Mac) - this selects the whole region and executes it."

[afischli]

4th issue: "You can have your cursor anywhere in this region and press Ctrl-Enter (Cmd-Enter on the Mac) - this selects the whole region and executes it." This is of course also not true and should be rewritten as: "You can have your cursor anywhere in this region and press Ctrl-Enter (Cmd-Enter or Shift-Enter on the Mac), which executes the entire region."

[afischli]

5th issue. I find the return to the semi-colon topic confusing. Thus I would suggest to actually say first nothing about the semi-colon and come to that topic only after having encountered an error. That is didactically much better. Thus delete these two sentences "Note also that each line of code ends with a semi-colon. This is how you separate lines of code in SC. If we didn't have a semi-colon between the two lines we would get an error." including the my previously suggested additional sentence "Having an extra semi-colon at the very end does not hurt and is tolerated for reasons of convenience.". Instead the sentence "In this case of course, it's the lack of a semi-colon at the end of the previous line." should read: "In this case, it's the lack of a semi-colon at the end of the previous line." and move the deleted sentences here, so that the paragraph reads all together now: "In this case, it's the lack of a semi-colon at the end of the previous line. Note that each line of code ends normally with a semi-colon. This is how you separate lines of code in SC. Since we didn't have a semi-colon between the two lines we have gotten an error."

Finally I suggest to add my additional sentence previously suggested after the example

"Call me ".post; "Ishmael?".postln;'

as a new paragraph before "A couple of more notes about ...". It reads: "Having an extra semi-colon at the very end does not hurt and is tolerated for reasons of convenience.". The rationale for that important explanation I have given previously.

[jamshark70]

So things get unnecessarily complicated and leave the beginner's understanding in a foggy state of not being sure what the role of a semi-colon really is...

13 years I've been using SC, and I've never seen one user -- not one, ever -- actually seriously get confused by this.

Other points are valid.

[jamshark70]

Also: Improvements are always welcome. Pull requests are ideal: "Here, I fixed it for you," rather than, "I would like to insist that somebody else fix it."

[crucialfelix]

re 1st: yes, you are right.

re 3rd: selecting by clicking on a word is an OS feature. selecting a block inside a parentheses by double clicking is a feature of the supercollider IDE, and it may not be working as advertised. the original help text was written for an older version of supercollider and they re-implemented some features in the new IDE such as this.

so you are quite right: it should say double click on the first or last line within the block.

thanks for the feedback afischli !

On Thu, Jan 7, 2016 at 10:54 AM jamshark70 notifications@github.com wrote:

Also: Improvements are always welcome. Pull requests are ideal: "Here, I fixed it for you," rather than, "I would like to insist that somebody else fix it."

— Reply to this email directly or view it on GitHub https://github.com/supercollider/supercollider/issues/1781#issuecomment-169613664 .

[afischli]

Finally: It is a bit late to explain something so elementary as multiple key shortcuts, since this has been used already early on, e.g. Ctrl-Enter/Cmd-Return only now, but at least it should be correct. The k needs to be replaced by p so that it reads: ".. (hold down the command key and the shift key, and then press p)."

[afischli]

@jamshark70 Let's not argue about the people who do not care too much about deeper understanding at the begin or simply got stuck and turned off at this point, regardless whether that has never gotten to your attention in the past 13 years or not. ;-) And please note, I do not the least insist on a formally correct definition, since that is anyway very difficult and confusing for beginners with a language not formally designed in a logical and straighforward manner and therefore complex (I have to admit that my first impression is the latter for SC). Therefore, to not confuse well educated people like me, one should at least be precise and find some language that is at least clear what to do for everyone. In my teaching experience, this is also what beginners need. Therefore I believe my suggestions ought to be helpful.

With respect of doing those changes myself: I do not (yet, perhaps) dare to do so. I am only responding to the very first impression with SC. I believe tutorials are important and need to be well written and are best written by someone experienced. Though I am also a very experienced computer scientist, I have nil experience with SC. Thus, I would prefer someone having the responsibility and experience with SC ought to make the needed changes and having the last word on what I suggested.

[jamshark70]

I don't particularly object to the changes. I do think the number of bytes spilt on semicolons in this thread is markedly out of proportion to the degree to which new users actually care.

Pull requests are actually conversations, much like this one. They are an excellent way to propose changes in detail. Nothing in PR goes into the master branch without being reviewed, discussed and amended if needed. There's never any harm in someone giving it a try, then.

I, for one, have rather limited time. Above, you've made a number of recommendations, some of which invalidate recommendations from earlier posts. For me to untangle them and then rewrite them to your satisfaction is likely to be a/ time consuming and b/ error prone (since you have something specific in mind). I believe a PR is the most efficient way to get precisely the changes you want. If you write something that's not exactly accurate, we can catch it in review and update the PR with further commits. No big deal.

[telephon]

Yes, if you could just correct the text in your own version and ask us to merge that, this would be very nice – your corrections are very welcome! Feel free to ask if you need help setting up a copy from which you can make pull requests.

[afischli]

Indeed I would need some help, since I do not want to mess up things. I have been consulting https://guides.github.com/activities/forking/index.html#making-changes and made some tests as described at that page, but nothing seems to really work as described there. So I am not sure I would do things right.

Notably, I did 1) Fork a test repository (Spoon-Knife) 2) Cloned the fork using GitHub Desktop 4) Created a new branch 5) Made some changes using my favorite text editor AlphaX 6) Committed those changes using GitHub Desktop 7) Believe to having pushed them by clicking on Sync in GitHub Desktop 8) But then everything looks different on GitHub (my account) as described on above page. Notably I can nowhere see the green button 'Compare & pull request'. E.g. at https://github.com/afischli/guide-github-pull-request/tree/1st-branch I see only a green button 'New pull request'.

Can anyone advise me what went wrong and what I could do to get the green button 'Compare & pull request'?

Thanks.

[telephon]

7) Believe to having pushed them by clicking on Sync in GitHub Desktop

No, push is an extra menu entry. There is also an entry called Create Pull request, that may help as well - I've never tried that one.

[afischli]

Indeed, I saw that now. Then the description at aforementioned web site is misleading, since all it states on push is this: "When you’re ready to push your changes up to GitHub.com, click on the Sync button, which is right above your list of changes.". Will try it out, whether that makes a difference and whether the wanted green button 'Compare & pull request' will then show up. The button "Create Pull request" from GitHub Desktop is not explained in aforementioned tutorial. No idea whether that might be an alternative. I simply tried to follow the tutorial.

[afischli]

Unfortunately nothing works as described in the tutorials. So I am pretty turned off and don't feel welcome. I wasted now already many hours in trying to figure out how I could make a contribution ending in a pull request. But I stop doing anything until I manage to get a tutorial trial working as described.

However, this seems impossible. It is very frustrating. I tried many tutorials, i.e. GitHub Help (https://help.github.com) or Understanding the GitHub Flow · GitHub Guides (https://guides.github.com/introduction/flow/index.html) or GitHub Flow – Scott Chacon (http://scottchacon.com/2011/08/31/github-flow.html) or GitHub Pull Request Tutorial (http://www.thinkful.com/learn/github-pull-request-tutorial/) but never get accurately what is described in any of those or believe they do not apply to my case. E.g. if I create a repo as described under GitHub Help it is empty and has nothing to do with SuperCollider, regardless how I name it. I guessed I should rather fork SuperCollider. But havn't dared to do so so far. So I concluded I SHOULD NOT create a repo, regardless what GitHub Help encourages/instructs me to do. This lack of a reliable help is quite messy and frustrating.

If anyone could help a bit, that would be great, despite this being a problem that has little to do with SC but is due to flaws in GitHub's documentation. But please, if anyone helps, it has to really work. Sorry, but I am about to lose my patience.

Thanks.

[jamshark70]

I apologize for leading you down the wrong path. I had assumed familiarity with git and github, but that was not a safe assumption.

Fwiw, my own workflow doesn't use any github desktop tools. I use qgit to handle some of the details of committing. Other git operations, I do at the command line.

1. On the github website, fork the supercollider/supercollider repository into my account. (Done once, ages ago).
2. The github site for my fork shows the repository address. I copy it and then, at the terminal, cd somewhere and git clone --recursive .... (substituting the address). You need --recursive if you plan to build your own binaries. Otherwise you can omit it. (This is also done once).

For changes:

1. Sync up by git checkout master, git fetch upstream and git merge upstream/master
2. New branch: git checkout -b branchName
3. Do stuff and commit.
4. git push origin branchName
5. Now visit supercollider/supercollider at github. It should show a button referring to your recently-pushed branch, offering to create a pull request. If it doesn't, the pull request section allows creating a PR manually from any branch.

Anyway, since I wasted your time (and since I was too dismissive of some of your concerns at first), I feel obligated to have a look at your revisions. In the next couple of days... I'll assign this issue to myself.

[telephon]

Unfortunately nothing works as described in the tutorials. So I am pretty turned off and don't feel welcome.

I am really sorry (mainly on behalf of git) for these troubles, your contributions are very welcome indeed. My own experience with learning git is similar! The good part of it is that once you know how to use it, it is applicable a lot – git is almost universal in software development today.

I hope @jamshark70 's explanation may lead you through. We should even simplify it more (for the most basic case) and add that in a place easy to find.

[afischli]

@jamshark70 for the kind help. Most helpful, but not yet all clear to me.

Please allow me ask for my understanding specific questions, since I would prefer to use 'GitHub Desktop' and do everything right. Note, I have all prepared, latest 'GitHub Desktop' version incl. CLTs is installed:

a) git init' or not 'git init'?: Instructions such as http://rogerdudler.github.io/git-guide/files/git_cheat_sheet.pdf offered at http://rogerdudler.github.io/git-guide/ state that I have to create my own repository (CLT: 'git init' on my local Mac) first as the very first thing. Is that correct? I guess the other tutorials talking about creating first a repo may mean the same thing. If that should be correct then I guess git does install some stuff in a dedicated git root directory where all clones from projects, including SC, have to go into. Right? Or does this 'git init' has to be done repeatedly on a per project basis, i.e. for SC, for BibDesk etc. (I participate in several open source projects, but needed so far never to use git).

b) Why is my fork from SC called 'Master' branch, while it is clearly not the master?: I forked now SC to my GitHub account. Again it surprises me that the default name of the branch at https://github.com/afischli/supercollider is 'Master'. I expected this forking to result in a new branch, my branch and nothing else. As a good name I would have expected something like 'Andreas' branch of supercollider' or something similar. Why is this fork so confusedly called 'Master' while it is clearly not the master, which is to my understanding at https://github.com/supercollider/supercollider only? Why am I not invited to give it a different name? And it seems I can't change that name.

c) When and why making another branch?: Somewhat related, do I get a branch or not, when I follow your steps? In my understanding a clone is not a branch? In my understanding a clone is simply an exact copy, e.g. from a remote repo to a local repo. Or in other words, why do tutorials recommend/instruct me to create first locally a new branch before starting to make changes, while I have just made remotely a new branch by forking the true master?

Sorry for asking these perhaps stupid questions from my currently confused understanding, but I always prefer to well understand what I am doing before doing it, but find no clear answers to these questions.

BTW, a good exercise for me would be to fix the typo I detected in the contribution from danielmkarlsson https://github.com/afischli/supercollider/commit/b0a7febc2e25d80a990a1ea461e99f3bf6cc4612 as committed on Sep 20, 2015. Any hints, best step by step list, on how to proceed there would also be most welcome in addition to answering my questions.

Thanks a lot for anyone answering.

[afischli]

I already made a first mistake by confounding the 'master' in my account with the true master open to anyone by giving a link in the last para of my previous comment, which is probably inaccessible to all of you. I presume the more useful URL for the contribution by danielmkarlsson, that should be really accessible to you all, is:

https://github.com/supercollider/supercollider/commit/b0a7febc2e25d80a990a1ea461e99f3bf6cc4612

Sorry.

[jamshark70]

Please allow me ask for my understanding specific questions, since I would prefer to use 'GitHub Desktop' and do everything right. Note, I have all prepared, latest 'GitHub Desktop' version incl. CLTs is installed:

I have never touched Github Desktop, and I have no idea how it works. All I can do is explain the operations that work for me.

a) git init' or not 'git init'?: Instructions such as http://rogerdudler.github.io/git-guide/files/git_cheat_sheet.pdf offered at http://rogerdudler.github.io/git-guide/ state that I have to create my own repository (CLT: 'git init' on my local Mac) first as the very first thing. Is that correct?

git init adds the git repository metadata (hidden .git folder) into a local directory.

But you aren't making a new repository. You're cloning one from a remote source. Git assumes in this case that you want the clone to be a fully functioning repository, so it "init"s automatically, for you.

I guess the other tutorials talking about creating first a repo may mean the same thing. If that should be correct then I guess git does install some stuff in a dedicated git root directory where all clones from projects, including SC, have to go into. Right?

Nope. There is an optional global git config, but it isn't required. Everything for a git repository lives in the repository's directory. The only thing that is required is that the repository contain a hidden .git folder. The metadata and revision history are completely encapsulated here. There is no need for any external folders.

Or does this 'git init' has to be done repeatedly on a per project basis, i.e. for SC, for BibDesk etc. (I participate in several open source projects, but needed so far never to use git).

Yes, git init or git clone.

c) When and why making another branch?: Somewhat related, do I get a branch or not, when I follow your steps? In my understanding a clone is not a branch?

A clone is most decidedly not a branch. Neither is a fork.

If you fork and then clone, you have your local repository, and there is the "origin" from which it is cloned (that's your fork on github), and the main SC repository, called "upstream." The dataflow goes local repository --> origin (by "git push") --> upstream (by pull request).

In my understanding a clone is simply an exact copy, e.g. from a remote repo to a local repo. Or in other words, why do tutorials recommend/instruct me to create first locally a new branch before starting to make changes, while I have just made remotely a new branch by forking the true master?

No, you haven't. You've made an independent copy of the repository. Branches are within repositories. Repositories are not branches.

Git branches have some refinements over, say, svn branches, but the concept is not radically different. If you've used branches in other tools, then you already have the basic idea.

b) Why is my fork from SC called 'Master' branch, while it is clearly not the master?: I forked now SC to my GitHub account. Again it surprises me that the default name of the branch at https://github.com/afischli/supercollider is 'Master'. I expected this forking to result in a new branch, my branch and nothing else. As a good name I would have expected something like 'Andreas' branch of supercollider' or something similar. Why is this fork so confusedly called 'Master' while it is clearly not the master, which is to my understanding at https://github.com/supercollider/supercollider only? Why am I not invited to give it a different name? And it seems I can't change that name.

Now maybe it makes more sense. Forking is not making a branch. Hence, you should not expect a different branch name from an operation (forking) that has nothing to do with manipulating branches.

Forking makes a copy of the repository. It would be very weird if the original master branch had to change name in a copy of the repository...

Sorry for asking these perhaps stupid questions from my currently confused understanding, but I always prefer to well understand what I am doing before doing it, but find no clear answers to these questions.

One nice thing about git is, all of your changes are strictly local at first. If you mess something up, you can delete your copy, refork/reclone, and nothing bad happens to the source repos. This is a big improvement over svn.

Sent with AquaMail for Android http://www.aqua-mail.com

[afischli]

@jamshark70 Thanks a lot. I am most grateful for your clarifications, notably that clone makes an implicit 'init git', that I merely need to clone to my local machine without making first a repo – despite all the hints to the contrary – and that a fork is not a branch. I start to understand things. But note, I have never done with svn anything else than user checkouts and my contributions were always only committed by the core team (AlphaX), me sending them my contributions by mail/entire files.

According to your excellent explanations I'd say what I get when I fork is a new repo with a single branch in it called 'Master', since that branch is simply a clone (or copy) of the original repo (what I think of as the true master) in the state that master was when I did that, right? Then my next question is immediately:

a) Can I sync my fork with the master to have really the latest version (one way sync only of course)? Or am I stuck with what I got the moment I made that fork? Or do I have to repeat forking, each time I want to get the latest version? I doubt that is correct, since you told me that I need to fork only once. But how can I update my fork to the latest version of the project, to the HEAD of SC? Another worrying me aspect in this context is the fact that I just saw that in each contributors fork I can have a look at other contributors repo's and there might be different comments added. So for a single file from a project there might be hundred of contributors and each of those forks might again have separate threads and discussions on the very same file. And there are easily thousand of files in a large project... A bit a daunting concept IMHO! Is that really as helpful? I see then here of course the need emerging for mechanisms to draw attention to changes, I guess that is the purpose of pull requests.

b) In my understanding I also typically sync only between my local clone and my remote repo/fork as hosted by github.com. Is that correct? Is then pushing something else than syncing, since I send/push my commits to the true master (supercollider/supercollider)? Or does it have to go through the fork on my account? If the latter is the case then I am confused, since consequences appear to me to be messy, unless I can first make sure my fork of SC contains throughout the latest data and can be made to be identical with the true master (also addressed in a).

c) Related once more: Can I directly update my local clone from the true master, e.g. by sync? And then the updating of the remote fork in my GitHub account takes place through my local repo? Again, this question boils down to not understand how I get with GitHub a clone from the latest version of the true master, the HEAD of SC as stored in the repo https://github.com/supercollider/supercollider.

Sorry for asking so many questions, but I hope to get soon to the pudel's core and will then have little need thereafter for questions and hope to be able to start contributing.

[afischli]

Now that I have done my first pull request for a typo (https://github.com/supercollider/supercollider/pull/1784) I would like to get to more of the substance of this issue. I need answers to fundamentals of SC, notably how to execute code in SC? BTW, I am familiar with almost two dozens of programming languages, with several very intimately, and I have worked through the SC tutorial to three quarters and done all suggested plus my additional exercises and still do not understand how to execute code. Why? Please, read on:

1) When is the short cut Cmd-Return working and when not? On my modern Mac systems (OS X 10.9.5 (Mavericks) or OS X 10.11.2 (El Capitan)) Cmd-Return seems never to do anything. On my music studio Mac (Mac OS X 10.6.8 Snow Leopard) it works, given I have selected some code snippet in the Tutorial window or the post window, but not when I have some code snippet selected in a saved file, the most likely case. So why not discard this shortcut and offer only Shift-Return to execute some code? I would then adjust the tutorial accordingly and mention shortcut Cmd-Return at most in the context of older systems (e.g. SC 3.6.5 running under older OS X such as Mac OS X 10.6.8 Snow Leopard).

2) Neither Shift-Return nor Cmd-Return work in the most likely case on a modern Mac (latest SC 3.7), i.e. when I wish to execute code from a saved text file. Then those commands merely delete (overwrite) the code and nothing else happens. Perhaps I am doing something wrongly, but I like to save my code permanently to files and work from there, not the other way round. So this is quite a serious issue for me.

3) What is the extension one should use when saving code snippets? Under Mac OS X 10.6.8 (Snow Leopard) .rtf seems to be the default. Under OS X 10.9.5 (Mavericks) none is suggested on my system and I used .txt as this is what I normally use in such a case for code.

Please answer so that I can start revising the tutorial.

Thanks.

P.S.: @jamshark70 and perhaps others: Despite my first AFAIK successful pull request I still need answers to my previously asked questions. Thanks a lot.

[jamshark70]

The default is rtf? That's... insane... Code documents should be scd.

I'm not on Mac so I can't confirm, but if in fact the OSX app tacitly encourages you to save as rtf, I'd say you should open another bug report. B/c that's just crazy.

Edit: I see, OSX 10.6, rtf, Mavericks, no default. Either way, that's not nice. But maybe OSX doesn't make it easy... I don't know, it's 5+ years now since I used OSX on any kind of regular basis.

Your other cmd-return problems should go away once you start using the right file format.

[jamshark70]

According to your excellent explanations I'd say what I get when I fork is a new repo with a single branch in it called 'Master', since that branch is simply a clone (or copy) of the original repo (what I think of as the true master) in the state that master was when I did that, right?

Not exactly. You're copying the repository. The original repository contains a number of branches. Hence, the copy of the repository should contain all of those branches.

a) Can I sync my fork with the master to have really the latest version (one way sync only of course)? Or am I stuck with what I got the moment I made that fork?

No, of course not.

https://help.github.com/articles/fork-a-repo/#keep-your-fork-synced -- section 3 explains how to connect your fork to the original. (In fact, I forgot to mention this in my earlier instructions.)

Then... https://help.github.com/articles/syncing-a-fork/ -- I have to admit, the dataflow here strikes me funny: main repository's commits --> fetched into your local repository --> merged into the local master branch --> pushed back to your github fork. The last step is not strictly required, though. jamshark70/supercollider-rename on github "is 296 commits behind supercollider:master," but my local copy is much more up-to-date.

In practice, people fork from the original-original. They don't fork from somebody else's fork.

Another worrying me aspect in this context is the fact that I just saw that in each contributors fork I can have a look at other contributors repo's and there might be different comments added. So for a single file from a project there might be hundred of contributors and each of those forks might again have separate threads and discussions on the very same file. And there are easily thousand of files in a large project... A bit a daunting concept IMHO! Is that really as helpful?

In practice, this doesn't actually happen. You're thinking too much: raising objections before observing how it actually operates in the real world.

I see then here of course the need emerging for mechanisms to draw attention to changes, I guess that is the purpose of pull requests.

Yes, precisely.

b) In my understanding I also typically sync only between my local clone and my remote repo/fork as hosted by github.com. Is that correct? Is then pushing something else than syncing, since I send/push my commits to the true master (supercollider/supercollider)? Or does it have to go through the fork on my account?

Not a concern, after you've learned how to sync your local repository.

You can push a local topic branch into supercollider/supercollider, but it's slightly less polite than pushing your topic branch to your personal fork. Pull requests work perfectly fine against your fork.

DO NOT push anything to the master branch on supercollider/supercollider!!! That's the "in-production" development branch. ALWAYS isolate your changes at first in a separate branch. Updates from other branches may be merged into master, at which point they go into production. This protects production code from accidents.

If you've set it up as github help specifies:

• local = on your hard disk;
• origin = your fork on github;
• upstream = supercollider/supercollider;

Then just remember: git push upstream master = BAD, BAD, DO NOT DO THIS EVER. You should develop a reflexive horror of the words "git push upstream." git push origin master is OK.

[afischli]

My user model for git

First @jamshark70, many, many thanks, the fog starts lifting. :-)

A major concern I had was how things would get synced, notably when creating a fork, an additional copy of the master project files, which may confuse or irritate many, notably when coming from svn. At least it did irritate me greatly and I saw it first as unnecessary, causing only syncing difficulties with little purpose.

Let me present the information I was looking for, a summary of what I learned so far (the user model of git) and please correct me, should I still err anywhere. I hope this might be useful for other beginners struggling with git as well:

Git uses key terminologies, which need to be understood. Here the key concepts and the jargon terminology. First there are typically three so-called repositories (repo), data storing places:

• upstream is the remote master project repository, e.g. https://github.com/supercollider/supercollider, maintained by the community. It contains all project files.
• origin is your personal remote copy of the project, a so-called fork at GitHub, e.g. https://github.com//supercollider, made once by clicking button ’fork’ at the upstream repo while having logged in as GitHub user . Note this can be done only using a browser, ‘GitHub Desktop’ can’t fork. Your fork keeps all your contributions separate from the upstream repo. Your fork is not private, it is visible to everyone logged in to GitHub and may contain specific discussions. Note, despite being separate, the fork can be easily updated/synced to the latest development state.
• local is the local git repository on your hard disk, a directory, e.g. ../supercollider, containing all project files plus hidden directory ‘.git’ and other auxiliary files needed for git to work. This local copy must be created by cloning once the remote origin, i.e. your personal fork, not the upstream, to the local machine. All files here can be freely edited with tools of your choice, Git will take care of the rest, i.e. detect changes by watching all files residing in repo local.

In addition there are branches within above 3 repos. Each repo contains at least one branch, the default branch, called Master. Branches serve separate development from the main branch, e.g. to try new things out first before they are released (deployed) to the general public. Whether to create or not to create a branch depends on the given circumstances. To make small changes, e.g. fix a typo, there is no need to create a branch and such changes are best done directly within the master branch of the local repo. Larger changes such as a subproject for a complex new feature, require to first create a branch (locally).

Then it is important that local edits need to be committed locally to become effective, then pushed to the origin, not the upstream (!), and then be announced to the community by pull requests. The core team of the project will then revise the pull requests and eventually merge the edits from your fork origin (remember it is public) into the upstream. Once that is done and you have synced your local repo (fetched and merged all latest edits) you can then update your local files to the latest development and sync back to your fork origin. As a result all three repositories should then contain identical project files.

All version control actions can be done either by using command line tool 'git' or application ‘GitHub Desktop’. In addition you need a browser to access the remote repos.

Do not follow the GitHub tutorials (!), they are misleading and are rarely helpful unless you are already very familiar with git concepts. For the CLT based technique there may be helpful: «git - the simple guide - no deep shit!» (http://rogerdudler.github.io/git-guide/). For using ‘GitHub Desktop’ again do not follow the help prominently offered there, i.e. the popup window, since it points only to CLT based techniques. Use this tutorial instead «GitHub Desktop User Guides» (https://help.github.com/desktop/guides/).

That's all folks!

[miguel-negrao]

Great that you took the time to read up on git, thanks for that. Yes, all of above is correct. In order to use git one needs to understand git's model more than one needs to memorize commands. Possibly you could check if some of this information is missing in the documentation in the SuperCollider site regarding using git and propose additions (via pull-request, which is nicely circular :) ).

[jamshark70]

Minor corrections:

A major concern I had was how things would get synced, notably when creating a fork, an additional copy of the master project files, which may confuse or irritate many, notably when coming from svn.

A notable weakness of svn is that commits are always public, meaning that erroneous commits always pollute the public repository. Git's distributed model means you can commit at will locally, and you have considerable power to reshape the commits locally before pushing to any public location. Your last commit was wrong? No biggie... git reset HEAD^ and you've rolled back on your machine (without losing file contents). No one outside will ever know. Or, you did 20 little commits but you want to publish them as 3 bigger commits: git rebase --interactive ... With this power comes the possibility of breaking things in other ways, but the freedom to mess up and fix it before publishing anything is a huge benefit.

To make small changes, e.g. fix a typo, there is no need to create a branch and such changes are best done directly within the master branch of the local repo. Larger changes such as a subproject for a complex new feature, require to first create a branch (locally).

If you want to make multiple, independent pull requests, they must refer to separate branches. Otherwise they are no longer independent. So I would recommend always creating a branch if the intent is to file a pull request, even if it's only a one-character typo. It is occasionally OK to commit a typo fix to master and push it to "upstream" directly, but only if it's very minor, and uncontroversial, and you are absolutely 100% certain you know what you're doing. If there's even a shred of doubt, branch and PR is the way to go.

Git branches are lightweight. Don't worry about overhead; there's almost none.

[telephon]

We should add this user model documentation to a place very well visible – it is really useful.

[afischli]

Sorry for asking, but perhaps some of you can point me where to best place this?

I quickly checked the help section, but I see nowhere any files dedicated to git. I searched and the only place where git seems to be mentioned is in «Using Quarks - A guide to Quarks», a section which has little to do with understanding git and contributing to SC.

Then @miguel-negrao mentioned to propose my summary as an addition to a "SuperCollider site regarding using git". Where is this site? If directed I can offer then to make this addition and create the PR. Please help.

[afischli]

@jamshark70 I tend to the philosophy keep it simple, would therefore prefer to have a few branches as possible, but I listen of course to more experienced users and I am happy to modify above text accordingly.

Let me then seek your advice on a practical example: This issue contains a sequence of 6, IMHO clear mistakes as I detected in the tutorial «Getting Started With SuperCollider». I understand jamshark70 that I should now at least make a branch. My plan is, I make 1 branch with corrections for all 6 problems resulting in a few commits. Then I file one pull request for all. Right?

[jamshark70]

"Keep it simple" in this case has an unfortunate side effect. Say you have two changes, A and B, that you want to be evaluated separately:

1. Commit A locally into master.
2. Push to "origin" (your fork).
3. Make a pull request (PR1) against your fork's master branch.

So far so good. Now, B:

1. Commit B locally into master.
2. Push to "origin" (your fork).

Now, when you go to make the pull request, you'll find that PR1 contains both A and B. If you file a new PR2, it will also contain both commits!

Pull requests are against branches, not specific commits. This is a good thing -- it allows PRs to be updated (to correct mistakes) before merging. If a PR were based on a commit, the only way to update would be to delete the old PR and resubmit, losing all the discussion history.

would therefore prefer to have a few branches as possible

Branches are lightweight. There's really no concrete reason to prefer this.

My plan is, I make 1 branch with corrections for all 6 problems resulting in a few commits. Then I file one pull request for all.

Yes!

[afischli]

I am also coming back to the rather fundamental point that Cmd-Return (on a Mac) does not work on an untitled not properly saved document. I thought about that and concluded this is clearly a bug. An application should always behave the same, regardless whether a document was previously saved with the proper extension or is in the state of being currently in state unsaved (On a Mac always a window with title "Untitled"). Since the untitled document is the very first thing one sees and the tutorial invites the beginner to use it, this bug is quite seriously confusing users. This gives sort of the bad impression: "Nothing works as described!". Don't forget, a tutorial is a business card.

However, if nobody has the time to fix this problem by fixing the bug, then I suggest to at least enhance the tutorial by adding a strong recommendation to first save 'Untitled' with extension '.scd' before using the window, to avoid the bad impression I got. I did of course save Untitled while working through the tutorial, but was nowhere taught what the proper extension would be and had also to suffer from the fact, that SC does not work anymore if the extension of the file is not '.scd' but '.txt' (actually I would say this to be another bug, since SC invited me to use extension '.rtf' or none at all, depending on version of SC and OS X). All giving a beginner like me the very bad impression that SC is not functioning in a reliable manner.

What do you recommend should I do: File this issue as a bug (I don't have the time to fix this myself and would not wanna do this as a novice to SC) or go the "pragmatic" way and enhance the tutorial accordingly?

This is the 7th problem I raise in this issue under the motto "Improve the tutorial to become really useful for beginners". Another branch needed in case you recommend me to go the "pragmatic" way?

[jamshark70]

Cmd-return: File it as a bug. Other Mac users need to confirm the behavior you describe.

I can't do anything concrete with this issue myself (being on Linux). But, I do recall cases of keyboard shortcuts being broken by conflicts against system settings (most likely input locale). It's entirely possible that it works exactly as described in the tutorial on a US or UK English keyboard, while another locale with more support for diacritics might trigger some weird condition that the Qt GUI backend doesn't handle exactly right. In that case, 1/ it needs to be investigated and 2/ it would exonerate the tutorial authors.

It could be something other than locale. We have plenty of German-language users, but I don't recall this issue being raised before.

[miguel-negrao]

Then @miguel-negrao mentioned to propose my summary as an addition to a "SuperCollider site regarding using git". Where is this site? If directed I can offer then to make this addition and create the PR. Please help.

http://supercollider.github.io/development/git-cheat-sheet.html

source in:

https://github.com/supercollider/supercollider.github.io

or edit via

https://github.com/supercollider/supercollider.github.io/edit/master/development/git-cheat-sheet.md

[afischli]

BTW, I work only with English (US American) locale (my OS language) but have to use International keyboards (with US ASCII layout), since living in Europe. But I doubt this matters at all, since Mac's API is layered and the keyboard does not really matter if the API is properly used by SC or Qt actually.

Then my guess is that the problem is more that of the state SC is in. As I said, keyboard shortcuts should be treated always the same (given all conditions are met) and must not depend on the state of the document! Not (yet) knowing the SC code at all, I doubt this is only the problem of the Qt GUI backend, since the document in focus is likely something SC needs to know of. So my guess is the problem is most likely that of a bad interplay between software parts, perhaps Qt GUI backend and SC. Likely not an issue of only a single location in the code.

Am I right filing a bug means opening a new issue?

[jamshark70]

And yet, you're the only Mac user I can recall reporting this problem.

Am I right filing a bug means opening a new issue?

Yes.

[afischli]

@jamshark70 With all respect, I disagree. You may have as many doubts you wish of course, but I am pretty good at spotting bugs and also quite experienced in user interface design (was at some time in my career my main job). I tested this and found it in SC 3.7, 3.6.6, 3.6.5 on 3 different Macs, also testing with virgin accounts (no configurations active, no preference changed from Apple's default), different keyboards (built in, Apple external, Logitech), under Mac OS X 10.6.8 (Snow Leopard), OS X 10.9.5 (Mavericks), and OS X 10.11.2 (El Capitan). All show consistently the same bugs.

Moreover, I detected it is clearly not only a shortcut issue, because the equivalent menu command fails also consistently. So as I stated earlier, it is likely to be an internal state problem, perhaps related to which document you wish to execute a code snippet from. The actual behavior depends whether you have a code snippet selected or intend to autoselect in window Tutorial, Untitled window, or saved document Window, then also depending on which extension. The command that works best is Shift-Return but it does not the same as Cmd-Return (it autoselects also first current line) and as I found out in my testing the equivalent menu command does the same thing. Actually, the behavior differences are quite complicated and subtle. Focus matters, cursor location matters, document type matters etc. etc.

AFAIK only older SC 3.4.4 running under Mac OS X 10.6.8 (Snow Leopard) works reliably as it should according to the descriptions. But there you do not have Cmd-Return for evaluation, you have only Shift-Return. My guess is that the trouble started with the introduction of the new GUI opening an Untitled window and the help pane and the Post window plus the introduction of two evaluation commands, i.e. Ctrl-Return/Cmd-Return (Language -> Evaluate Selection, Line or Region) in addition to the old Shift-Enter/Shift-Return (Language -> Evaluate Selection or Line). Moreover, given current behavior, the menu commands are not equivalent with the shortcuts coming with them. Why should Shift-Return work by autoselecting first the line the cursor is in and then execute/evaluate, while having the cursor at the exactly same place and choosing the menu command results in no such autoselection and then fails to execute anything (the latter being rather logical)?

BTW, note, those menu commands and their shortcuts can be made to work properly though, but only if one executes them in a properly saved document. That may explain why few complain. But the tutorial says you should be able to work the same, regardless whether from the Tutorial window or not, e.g. executing 'hello world'. Unfortunately, this never works as described. Of course, an alternative might be to make all evaluations in the tutorial fail, and totally discard the current tutorial philosophy of executing from the tutorial window all examples, i.e. rewrite it to work only from properly saved documents. But that seems to me to be too much trouble, which is not worth it. Better make SC work really as described and intended. In my decades of programming practice, in the end that pays out the most.

To wrap up: Shift-Return works the best, but not always, since it does not work if the document was saved at some point in the past and does not have the proper extension. Cmd-Return works 2nd best. Equivalent menu commands (Language -> ) also fail always when the shortcut fails, but even more so. Menu commands work the least reliably. There are cases, e.g. code snippet in the Tutorial, where no evaluation/execution is possible via the evaluate menu commands, only some of their shortcuts work. I 'm afraid I have to insist, all is very confusing and gives a very bad impression of a poor user interface design.

BTW, I for one, was then on the verge to forget about SC and contemplating shelling out the price for commercial products (MAX and Ableton Live). Only their rather steep price made me hesitate and I tried to give SC another chance, having seen that it should be quite powerful. Since I have been or am involved in many open source projects, there are some (e.g. Thunderbird is among them) that are unable to fix well identified, serious bugs for years if ever. Open source is only good if a lot of care is given to consistency and reliability, so that the niftiness can really be accessed by all. And that experience should be offered throughout. Therefore I'd say the business card matters. This is IMHO the reason why I opened this issue in the first place.

[telephon]

Is this fixed, or still needs work?

[afischli]

No #1786 it is not fixed. I still owe a clean test example that really shows the problem. Here you go

(
1+1; // put the cursor into this line and press Cmd-Return => you get 3, press Shift-Return => you get 2 (All as expected)
1+2;
)

{ Saw.ar(LFNoise1.kr(1).range(100,[200,300]) }.play;

Above code causes no problems and all works as expected. However, if you reverse the ordering to this:

{ Saw.ar(LFNoise1.kr(1).range(100,[200,300]) }.play;

(
1+1; // put the cursor into this line and press Cmd-Return => you get 2 but should get 3, press Shift-Return => you get 2
1+2;
)

You no longer get what you expect, i.e. the parser fails to execute the correct statements within the region as defined by the parantheses. The reason is only the presence of a mistake before/above the region instead of after/below the region. The mistake is in the Saw.ar line, BTW a line taken from the Multichannel-Expansion guide (but now fixed cf. https://github.com/supercollider/supercollider/commit/b54e617f3b7c3b824d4fa8ab57e8814e1d63e6c9).

I believe the parser should always evaluate correctly everything within a region as defined by parantheses regardless of what is outside of the region.

Andreas

P.S.: Above described behavior tested once more, now using SC SuperCollider 3.7.0-beta1 Built from branch 'HEAD' [9899190].

[telephon]

I believe the parser should always evaluate correctly everything within a region as defined by parantheses regardless of what is outside of the region

I agree very much. The fact that another line has a syntax error shouldn't influence what the rest of the code does. The name of our current issue doesn't reflect this. I suggest we start a fresh one, with just this reproducer.

[telephon]

Ah I just saw, it's here: #1786. Can we close the current issue and continue there?

[afischli]

Sure, that is indeed better.

I have, however, still some issues with some of the more fundamental concepts of OOP as badly explained if at all in the 'Getting Started Tutorial'. Thus further improvements are needed. But I am happy to open another issue on those as I find the time to attend to them.

[telephon]

yes, I am entirely sure that much can be done in this area – so any contribution is very welcome. If you have suggestions, you can also just make a pull request. But if there is something you don't know a solution for, open an issue, that is a good way to keep it in "mind".