Changes

Jump to navigation Jump to search

Contributing to Zynthian Development (view source)

Revision as of 20:05, 29 January 2024

11,423 bytes added ,  29 January
→‎A first time developer
Line 22: Line 22:  
It is perfect understandable if you are approaching this for the first time, with a burning desire to solve a specific musical dilemma with code. Treat it as an opportunity to learn. It is a process that can, at first, appear overly involved and, perhaps, a little bureaucratic, but there are good reasons for the approach that's taken. It has succeeded to keep track of enormous code bases securely, sometimes in the face of actively hostile actions by others. It is this very characteristic that means that many open source projects operate that way, and may give people an insight into quite what 'open source code visible to all really' means for us.   
 
It is perfect understandable if you are approaching this for the first time, with a burning desire to solve a specific musical dilemma with code. Treat it as an opportunity to learn. It is a process that can, at first, appear overly involved and, perhaps, a little bureaucratic, but there are good reasons for the approach that's taken. It has succeeded to keep track of enormous code bases securely, sometimes in the face of actively hostile actions by others. It is this very characteristic that means that many open source projects operate that way, and may give people an insight into quite what 'open source code visible to all really' means for us.   
 
Also this robustness should resolve you of fears about 'doing some damage'. This well walked path of forking a repository, and making a Pull request protects you the community from yourself in an agreed fashion.  
 
Also this robustness should resolve you of fears about 'doing some damage'. This well walked path of forking a repository, and making a Pull request protects you the community from yourself in an agreed fashion.  
 +
    
=== Could you tell me about the codebase? ===
 
=== Could you tell me about the codebase? ===
Line 32: Line 33:     
It's open source. Absolutely whatever they want to do . . .  
 
It's open source. Absolutely whatever they want to do . . .  
 +
 +
For example.. These are devices that have code written specifically for them....
 +
 +
[[Supported MIDI controllers|Supported_MIDI_controllers]]
    
Personally I do soundscapes, church bells and cajon enhancement, and much of this built without any direct purchase from the zynthian site. The Hardware designs are up on the site if you want to make your own. You'd probably even get advise on how to do it on the forum if you ask ...
 
Personally I do soundscapes, church bells and cajon enhancement, and much of this built without any direct purchase from the zynthian site. The Hardware designs are up on the site if you want to make your own. You'd probably even get advise on how to do it on the forum if you ask ...
Line 39: Line 44:  
Probably to do something with a particular piece of equipment that you want to customise to aid you in your sound based endeavours.
 
Probably to do something with a particular piece of equipment that you want to customise to aid you in your sound based endeavours.
 
The output of MIDI based equipment presents it's self easily to a python code base that allows messages to be detected in an orderly fashion and then pretty much any aspect of the zynthian can be modified to obey your will. This has grown up from user dialog within the forum [https://discourse.zynthian.org/ Zynthian Forum]which is an excellent place to start with questions, suggestions and the truly crazy range of things people do with these machines.
 
The output of MIDI based equipment presents it's self easily to a python code base that allows messages to be detected in an orderly fashion and then pretty much any aspect of the zynthian can be modified to obey your will. This has grown up from user dialog within the forum [https://discourse.zynthian.org/ Zynthian Forum]which is an excellent place to start with questions, suggestions and the truly crazy range of things people do with these machines.
 +
 +
Here's the current list of devices...[[Supported MIDI controllers|Supported_MIDI_controllers]]
    
=== Can I do damage to MY zynthian with the code I write ? ===
 
=== Can I do damage to MY zynthian with the code I write ? ===
Line 55: Line 62:     
No. Your code will be checked by people who control access to the core repository that you get your code from. They will not allow anything into the code base that they don't trust or that doesn't meet house rules about how stuff is written and presented.
 
No. Your code will be checked by people who control access to the core repository that you get your code from. They will not allow anything into the code base that they don't trust or that doesn't meet house rules about how stuff is written and presented.
 +
    
=== How is code of the zynthian maintained? ===
 
=== How is code of the zynthian maintained? ===
 
You can log onto a Zynthian itself as the root user if you have the password (it's set to raspberry), but you might well change it on a performance machine. People will find it very amusing to log onto your machine pre or during performance if they can, and if you don't change the password....  
 
You can log onto a Zynthian itself as the root user if you have the password (it's set to raspberry), but you might well change it on a performance machine. People will find it very amusing to log onto your machine pre or during performance if they can, and if you don't change the password....  
 +
 +
[[File:A-terminial-sshing.png|600px|center| An ssh terminal from a host computer (not necessarily yours ....]]
 +
    
You and they (if you haven't changed the password)  can, and do pretty much anything you want as it it nothing more or less than a raspberry Pi of various vintages running an operating system. So you can edit files to your hearts content and very quickly render your Zynthian unplayable if you don't know what you are doing.
 
You and they (if you haven't changed the password)  can, and do pretty much anything you want as it it nothing more or less than a raspberry Pi of various vintages running an operating system. So you can edit files to your hearts content and very quickly render your Zynthian unplayable if you don't know what you are doing.
Line 64: Line 75:  
and there are code editors that operate entirely round the command line, allowing you to change the contents of files on the machine.  
 
and there are code editors that operate entirely round the command line, allowing you to change the contents of files on the machine.  
   −
Here there is no protection. it's your machine and you can break it as you wish, and whilst you will almost certainly get help on the discourse forum, this is not the sort of activity to indulge in twenty five minutes before your performance. It easy to become the essential technician beloved and feared in equal measure, but probably the first concept to learn is stable . . .  
+
Here there is no protection. it's your machine and you can break it as you wish, and whilst you will almost certainly get help on the discourse forum, this is not the sort of activity to indulge in twenty five minutes before your performance. It easy to become the essential technician beloved and feared in equal measure, but probably the first concept to learn is the stable branch . . .  
      Line 88: Line 99:  
This is your protection from your own misdeeds with code. In fact it is sensible to keep at least two ssd's with a known good stable version on so you can give the zynth a brain change and keep a separate ssd for your code projects, but if you trash a part of webconf, then you have little or no easy way onto the machine, and you will need your backup... You have been warned!
 
This is your protection from your own misdeeds with code. In fact it is sensible to keep at least two ssd's with a known good stable version on so you can give the zynth a brain change and keep a separate ssd for your code projects, but if you trash a part of webconf, then you have little or no easy way onto the machine, and you will need your backup... You have been warned!
   −
So now we know how to switch between different branches of code how do we actually set up this new branch?
+
So now we know how to switch between different branches of code how do we actually set up this new branch?  
 +
 
 +
Is there some magic software tool...?
    
==== So what is an IDE ?====
 
==== So what is an IDE ?====
Line 134: Line 147:  
==== Where are the zynthian source files located on a zynthian? ====
 
==== Where are the zynthian source files located on a zynthian? ====
   −
The zynthian software exists as a set of directories ( or folders if you prefer) in a directory on the zynthian called  ...../zynthian.
+
The zynthian software exists as a set of directories ( or folders if you prefer) in a directory on the zynthian called  ...../zynthian.  
    
[[File:Zynthian-home-directory.png|600px|thumb|center|Zynthian home directory]]
 
[[File:Zynthian-home-directory.png|600px|thumb|center|Zynthian home directory]]
Line 155: Line 168:  
There are magic incantations to control zynthian via systemd  
 
There are magic incantations to control zynthian via systemd  
   −
systemctl stop zynthian
+
systemctl stop zynthian
−
systemctl start zynthian  
+
systemctl start zynthian  
−
systemtl status zynthian
+
systemtl status zynthian
    
So to stop a running zynthian you issue the first of these and this will tell systemd to ignore the restart so you can take over the running of it.
 
So to stop a running zynthian you issue the first of these and this will tell systemd to ignore the restart so you can take over the running of it.
 +
 +
==== How do I start a X11 windows server so I can run the code in a debugger? ====
 +
 +
Once you have stopped the zynthian process you can start it within the VSC debugger which is a good thing, but to allow this to happen you have to start the X11 Windows server to allow you to have something to connect to.
 +
 +
To do this in the window you typed systemctl stop zynthian type
 +
 +
X -r -s 0
 +
 +
You can then start the Debuuger in VSC.
    
==== How do I tell the world about my contribution...? ====
 
==== How do I tell the world about my contribution...? ====
Line 185: Line 208:     
So we better write some code.
 
So we better write some code.
 +
 +
<br clear=all>
 +
 +
=== It is 'suggested' one creates a task/issue? how do I do that ? ===
 +
 +
"it's a good habit to create a task/issue associated with more relevant changes"
 +
 +
Goto the zynthian issue tracker github page...
 +
 +
[[File:Zynthian-issue-tracker-page.png|600px|thumb|center]]
 +
 +
<br clear=all>
 +
 +
Then fill out something relevant
 +
 +
[[File:Duo-piano feature request.png|600px|thumb|center]]
 +
 +
<br clear=all>
 +
 +
==== So what have we gained here ? ====
 +
Well, the communal Zynthian entity gains an area of interest. Even if the task, dies on the vine, and nothing more gets done, there is a possible development signposted. You also get a unique identity number that goes into the Zynthian event queue. #941 in this case. This is an identifier you can add into a connect with Pull requests so the call for work and the doing of work can be related, tracked and pull requested, accepted tested and  completed.
 +
 +
This sort of structure within a project like Zynthian is a very good thing. And if precisely scratching your name into a spaceship excites you, then take this as an early buzz.
 +
 +
[[File:Zynthian Issues page.png|600px|center]]
 +
<br clear=all>
 +
 +
Because an event could be allocated to somebody else at some later time which means the code magically appears from someone you probably would never have met. Of course if you go ahead yourself and write it then so much the better. You move that one step closer to the "Had An Open Source PR accepted"
 +
 +
The github environment allows these relationships to be managed and the more structured this stuff is the less intimidating it becomes. . .
    
<br clear=all>
 
<br clear=all>
Line 238: Line 291:     
[[File:Vsc start up.png|600px|thumb|center]]
 
[[File:Vsc start up.png|600px|thumb|center]]
 +
 +
<br clear=all>
 +
 +
Give it a local directory. I store my stuff under Code but it really is up to you. Try to be structural.
 +
 +
[[File:Git-clone-destination-folder.png|600px|thumb|center]]
 +
 +
<br clear=all>
 +
 +
And there we have a git repository located on our host machine, which is useful upto a point but isn't actually located on the zynthian  . . .
 +
 +
[[File:Vsc-zynthian.png|600px|thumb|center]]
 +
 +
<br clear=all>
 +
 +
==== How Do I access code on my zynthian from my host machine? ====
 +
We need to use  Visual Studio Code(VSC) Remote Explorer to allow us to add on to the zynthian and install enough of an environment to allow VSC to seamlessly pass code between the environment and the desktop machine.Frankly sometimes it feels like magic, and for anyone who has read my previous attempts to do this sort of thing you spent a lot of time making sure the shaky old connections required behaved as machines are restarted and stopped and broken and goodness knows what lse. VSC relly sorts this out nicely, and it's a blessing. Indeed it is so tenacious in how it manages connections that the following image is actual a bit of a manufactured effort, but worry no it does it all very well.
 +
 +
 +
select Connect to and enter root@zynthian.local or if you have renamed your zynthian as I tend to do to something like root@zynthian-rack2.local you put that in and enter the password for the machine. You will find yourself doing this password entry a fair bit. There are ways to make this once only per machine turning on but we will skip over that for now.
 +
 +
[[File:Remote-explorer.png|600px|thumb|center]]
 +
 +
<br clear=all>
 +
 +
And we now get a new item in the Remote Explorer desktop and are returned to the VSC setup page to describe where we want to locate this connection to the remote machine and it is important that you put
 +
 +
/home/pi/zynthian-ui  in here. If you have /zynthian/zynthian-ui in her which might seem like it should work it wont for reasons to do with the long term migration to a more structured system. Don't worry it's in hand.
 +
 +
[[File:Remote-machine-home-directory.png|600px|thumb|center]]
 +
 +
<br clear=all>
 +
 +
So we now can examine and edit the code on the zynthian as thou' it is on our desktop... Which is kind of cool.
 +
 +
[[File:Remote-rack2-code display.png|600px|thumb|center]]
 +
 +
<br clear=all>
 +
 +
==== How Do I stop being asked for my password? ====
 +
 +
on your host machine type:
 +
 +
ssh-copy-id root@zynthian-your-machine-name.local
 +
 +
This will copy the key from your host computer to your remote host, where it will allow you to log on without providing the machine password each time, just a first confirmation by asking for your passphrase NOT your password. and when you need to enter the password the first time you will be asked for you pass phrase, if you set one, and since you have probably set this up for github you will have done,
 +
This should reduce the chatter a fair bit, but it may still occasionally ask just out of a certain degree of paranoia.. .
 +
 +
<br clear=all>
 +
 +
==== How Do I redirect the zynthian code in zynthian-ui to my personnal repository rather than the zynthian master I forked from ? ====
 +
 +
We need to edit a specific file on the zynthian within the zynthian-ui folder.
 +
It's in a hidden directory .git within the /home/pi/zynthian-ui folder so it won't show up with the ls command, use the ls -las form instead to see it..
 +
Now all this can be done from within VSC using a terminal os you have a nicely set up ssh connection to the machine all maintained by VSC. This terminal is in the lower right hand of the window and it saves you the trouble of having to set up separate connections to do basic housekeeping.
 +
Because this file is actually specifically kept out of the repository it doesn't appear in the VSC code listing so we have to go and abuse it by hand, which is why we are using the terminal . . .
 +
The terminal opens up in the zynthian-ui folder because that's how we configured it so all we have to do is type
 +
 +
cd .git
 +
 +
[[File:Remote-rack2-code display.png|600px|thumb|center]]
 +
 +
<br clear=all>
 +
 +
if you now type
 +
ls -las
 +
you should see this sort of thing ...
 +
 +
root@zynthian-rack2:/home/pi/zynthian-ui/.git# ls -las
 +
total 92
 +
 +
  4 drwxr-xr-x  8 root root  4096 Jan 20 21:46 .
 +
  4 drwxr-xr-x  14 root root  4096 Jan 15 11:21 ..
 +
  4 -rw-r--r--  1 root root    16 Jan 19 15:47 COMMIT_EDITMSG
 +
  4 -rw-r--r--  1 root root  220 Jan 20 21:02 FETCH_HEAD
 +
  4 -rw-r--r--  1 root root    24 Jan 20 21:44 HEAD
 +
  4 -rw-r--r--  1 root root    41 Jan 20 21:02 ORIG_HEAD
 +
  4 drwxr-xr-x  2 root root  4096 Sep  6  2020 branches
 +
  4 -rw-r--r--  1 root root  726 Jan 20 20:55 config
 +
  4 -rw-r--r--  1 root root    73 Sep  5  2020 description
 +
  4 drwxr-xr-x  2 root root  4096 Sep  6  2020 hooks
 +
32 -rw-r--r--  1 root root 32619 Jan 20 21:45 index
 +
  4 drwxr-xr-x  2 root root  4096 Sep  6  2020 info
 +
  4 drwxr-xr-x  3 root root  4096 Sep  6  2020 logs
 +
  4 drwxr-xr-x 133 root root  4096 Jan 19 15:47 objects
 +
  4 -rw-r--r--  1 root root  334 Aug 25 00:11 packed-refs
 +
  4 drwxr-xr-x  5 root root  4096 Sep  6  2020 refs
 +
 +
we want to modify the config file in this folder... So lets ook at this file first to see whats in it . . .
 +
 +
cat config
 +
 +
root@zynthian-rack2:/home/pi/zynthian-ui/.git# cat config
 +
 +
[core]
 +
        repositoryformatversion = 0
 +
        filemode = true
 +
        bare = false
 +
        logallrefupdates = true
 +
[remote "origin"] 
 +
        url = https://github.com/zynthian/zynthian-ui.git
 +
        fetch = +refs/heads/*:refs/remotes/origin/*
 +
[branch "master"]
 +
        remote = origin
 +
        merge = refs/heads/master
 +
[branch "testing"]
 +
        remote = origin
 +
        merge = refs/heads/testing
 +
[branch "staging-2209"]
 +
        remote = origin
 +
        merge = refs/heads/staging-2209
 +
[branch "stable"]
 +
        remote = origin
 +
        merge = refs/heads/stable
 +
[branch "staging-2307"]
 +
        remote = origin
 +
        merge = refs/heads/staging-2307
 +
[branch "chain_manager"]
 +
        remote = origin
 +
        merge = refs/heads/chain_manager
 +
 +
 +
We want to change the line
 +
url = https://github.com/zynthian/zynthian-ui.git
 +
 +
to point to our own repository, which in my case is
 +
 +
url = https://github.com/wyleu/zynthian-ui.git
 +
 +
to do this we use a little command line text editor called nano...
 +
so we type
 +
nano config
 +
 +
Control-X to leave Control-O to write out the file and arrow keys move you around in the file
 +
 +
[[File:Nano-git-config-file=edit.png|600px|thumb|center]]
 +
 +
<br clear=all>
 +
 +
And you have now redirected your zynthian to look at your repository on github as it's ultimate origin file . . .
 +
 +
git pull will now cement this relationship.
 +
 +
<br clear=all>
 +
 +
==== How Do I Start a new branch and what should I call it ? ====
 +
 +
The VSC status bar at the very bottom of the screen contains a lit of useful information.
 +
It shows the remote machine you are logged onto and it shows the current branch you are located on.
 +
 +
[[File:Making a new branch.png|600px|thumb|center]]
 +
 +
Indeed there are useful plugins that can be added that will show git tram lines and such which are very useful . . .
 +
but if you press on the testing button in the status bar you will be presented with a dialog for adding a new branch .
 +
 +
Quite what to call it is upto you but remember it will live long in the github zynthian home, so choose something relevant that you can remember what it's about at some point in the future.
 +
If it's too scurrilous your Pull Request will be rejected and you will be asked to change it to something more aligned with house style ... Benevolent dictators are perfectly entitled to behave like that .
 +
 +
In summary.
 +
git doesn't forget unless you beat it very hard with a stick cos remembering what happened is it's very purpose in life.
 +
 +
<br clear=all>
 +
 +
==== How do I switch to different branches when I'm developing? ====
 +
 +
Simply use the branch name switch down on the status line at the bottom left of the vsc window. Here is is set to the branch name I created Duo-piano-device
 +
 +
You can also see that I have added three device files into the ctrldev directory which is the code I working on...
 +
 +
[[File:Git-branch-switch.png|600px|thumb|center]]
 +
 +
<br clear=all>
 +
 +
==== Can I see a diagram of the my various zynthian various branches? ====
 +
 +
Here is the git graph vsc plugin showing tramlines for this repository. You will need to install this plugin to get this.
 +
 +
[[File:Git-tramlines.png|600px|thumb|center]]
 +
 +
<br clear=all>
 +
 +
==== Can I see a diagram of the various branches in the zynthian github page ? ====
 +
 +
From the github.com/zynthian/zynthian-ui/  you can select insights in the top menu and then Network in the left hand vertical menu. Github will chug away for a little while having a think then show you this, which now features the duo-piano-device branch waiting for me to submit the completion of the code with some more commits and then the pull request which, if successful will result in the branch being merged into testing, and at some later date in stable .  . .
 +
[[File:Zynthian-ui-networks.png|600px|thumb|center]]
    
<br clear=all>
 
<br clear=all>
Wyleu
584

edits

Retrieved from "http://wiki.zynthian.org/index.php/Special:MobileDiff/13247...13352"

Navigation menu