Contributing to Zynthian Development

1 Contributing to Zynthian

We would appreciate you to use the tools we use for developing, as it's a lot easier for coordinating the tasks, having traceability, testing, merging changes and of course, attributing the merit of every fix or improvement.

We use git as versioning tool and github as repository server and issue/task tracker: Zynthian's Repository Index

If you are a punctual contributor, you should follow this procedure:

• fork the repository
• make the changes
• test it
• make a pull request

When you are a habitual contributor, you will receive write access to the repositories you master and would use development branches instead of forking/pull-requesting.

Also, it's a good habit to create a task/issue associated with more relevant changes, specially if you are a newcomer. In such a way other developers will be informed of your intention of implementing a new feature or fixing a bug and will avoid overlapping efforts, at same time allowing other developer to contribute to your task by adding useful knowledge and alternative approaches.

1.1 A first time developer

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. This project, Zynthian, is based predominately in the python language with various whirling bits of C & C++ doing the heavily mechanical tasks down in the bowls where life is cheap, and code turns precisely. The python is a much more starter friendly world where you define what you want to do, and this gets translated into the sort of coal one can feed into the boilers down below.

1.1.1 So why might you want to write some code for a zynthian?

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 Zynthian Forumwhich is an excellent place to start with questions, suggestions and the truly crazy range of things people do with these machines.

1.1.2 Can I do damage to MY zynthian with the code I write ?

Yes, absolutely. With power comes responsibility.

But there is an important distinction between hardware and software. You can produce an inoperable zynthian with a badly placed code edit, but, you can't actively mechanically damage the machine itself by typing garbage. You simply correct the code fault and the damage its done, or at worst put in your backup ssd and things are good again.

This doesn't mean plugging the output of your 100W amp into the audio input of a zynth isn't going to damage it. It will and that's the world of hardware...

It's an important distinction.

1.1.3 Can I do damage to The whole zynthian code system with the code I write ?

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.

1.1.4 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 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. There is an entire linux world built around what is called a terminal, which contains a command line that you literally type commands into and press enter to get them todo things. Zynthian has one of these,

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 . . .

1.1.4.1 So what is a branch?

It's a slightly different version of the code files that a programme running on the zynth keeps track of, allowing you to move around between your different versions and accept of reject changes you have made. This all operates under a programme of some renown and reputation called git, which was written by the same bloke who was largely responsible for the Linux code base, which is used to house the linux code base itself, you are building on the work of giants. ... and riban.

There are many, many introductions to git Getting started with git and it has a certain reputation for complexity, but it rigorously hangs on to any code it is asked to look after even thou' this can be a mixed blessing if you are messy as I am. But it can be operated from the command line but it's better to use an IDE (Integrated Development Environment) which makes it all push button, more on this later.

Git also works peer to peer. This simply mean that rather than some of the older repository managers, every git instance running on a machine has a similar level of importance to every other, so you don't need a running central server to allow you to operate. That is a big feature that you don't appreciate until you DO work with the mega server in the middle with all it's associated limitations. This doesn't mean there isn't a a central repository where all the good stuff lives but it does mean that git allows you to make your own little development world where you do no damage to anybody else and you get all the control of being able to set up branches that are differing version of the code

1.1.4.2 Is Stable the best Branch to use?

Stable is the particular branch of code that is know good and behaves in a fashion that will match the documentation. It wont be cutting edge, but it will behave itself, precisely as you expect, during the performance so this is what you should be initially taking on stage.

The good news is if you can get enough of a Zynthian running to open up it's inbuilt webserver, forever known as webconf in these parts, you can select an option that will allow you to return to the stable state.

In the above example, where a little development is being done, the zynthian-ui ( the main zynthian code that controls the Touchscreen display and the main audio and midi functionality is set to another branch. Selecting the stable check box will get you back to your stable structure, and not destroy your edited code in this separate 'branch' called DUO Piano code if you have behaved properly in setting this up.

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?

1.1.4.3 So what is an IDE ?

We could operate all of this using the commaand line and git commands, but unless you really want to, don't. Use an IDE.

an IDE (Integrated Development Environment) is a collection of programmes that work together to ease the difficulties of acquiring, writing, modifying, testing, debugging code you write along with the possibility of many, many other functions you probably never considered. At the moment there is one that seems to be really sweeping the board with this ( yes, i know, emacs users, but I worked on pycharm and intellij and I know which I prefer out of the three).

It's Microsoft's Visual Studio code, https://code.visualstudio.com/ know to friends and enemies alike as VSC.

1.1.4.4 So what is a host machine?

Visual studio code is a considerable piece of software, Microsoft know an awful lot about writing code and they have realised presenting an suberb, well maintained IDE into the hands of absolutely anybody with a desire to write code. If you date back far enough to remember "a computer on every desk running Microsoft software" you might generate a rye smile at this point, but the software world is a very different place now, and Microsoft are perfectly willing to produce their IDE for every conceivable platform and operating system they come across and make it work. Anyone who plays around with Arduino's and such will find vsc's platformIO plugin is a considerable improvement on the Arduino's own IDE, and plugins like this are the secret of VSC. The Python environment is a plugin, tools to view git repositories are a plugin, remote access components are a plug in . I haven't looked but I don't doubt there is something MIDI related plugin out there . . . So we have a considerable chunk of code to run, which we are going to use to write a considerable chunk of code on a Raspberry Pi... Can you run VSC on a Raspberry Pi? Well yes you can, indeed I have run my vsc environment on a Pi4. But I wouldn't run zynthian and the VSC code on a zynthian. There is a cleverer way. You use the remote connection plugin, to access a separate Zynthian doing musical stuff. The vsc remote component installs itself onto the pi, once you present it with the correct password ( Did I mention about getting your passwords sorted out...?), and it handles many, many areas of this process that you can lose yourself into setting up yourself. I have written this process up for other environments and it was ..... Involved. OK vsc advert over.

So Our development environment consists of two machines, one is the zynthian itself, and the other is another computer running the vsc code.

This other machine is the host computer and it can be any number of bizarre, powerful, stylish, home built, clapped out, PC's and goodness knows what else, but as long as it runs VSC you are good to go. As I say my host machine is now a Pi5 running VSC very effectively, but your's could be MAC or a PC or goodness knows what else. This is why using a specific IDE provides dividends because we don't need to explain all the different access mechanisms for all these machines. Look up how you install VSC on your host machine and do that. It's pretty easy and if anyone wants to write up specific versions then great! just say so on the forum.

1.1.4.5 How do I install VSC on my host machine?

Go to VSC Download page and pick the appropriate version. For your particular Pi OS. If you are running 64 bit software pick .deb arm64, if you are on a 32 bit Pi OS then pick .deb arm32.If you are on MAC or PC then download accordingly.

VSC Download Page