Jamulus project/source code guideline

[corrados]

This is the current Jamulus project/source code guideline.

NOTE: This list should be adjusted to recent requirements to the Jamulus software! Please post your opinions in this thread. The list will then be updated accordingly.

1. Stability
   This is an important requirement for the Jamulus software. Much much more important than any new feature. Nothing is more frustrating than running a headless Jamulus server and from time to time it just crashes/disappears from the server list. It is particularly important for usecases like the Worldjam. Imagine the server or one client would crash during a live jam. That is the reason I am very cautious with changes to the core components of Jamulus.

2. I prefer the Keep it Simple and Stupid and Do One Thing and Do It Well principles.
   If a software has too many features, it is hard to keep everything consistent and the tests for stability and correct functionality takes a lot of time. So too many features increase the maintenance work and also risk the stability. Therefore for some functionality like "finding musicians/social functions" I prefer that this is managed by external tools like a website. TO BE DISCUSSED (see below).

3. Focus on what is the strength of the Jamulus software and improve that.
   There are many other solutions for realtime online jamming available. But it seems Jamulus with its client/server system and minimalistic GUI is kind of unique.

4. Source code consistency.
   I very much try to keep the source code "way of coding" and "code style" consistent. That makes understanding and maintaining the code much easier. TO BE DISCUSSED (see below).

5. Jamulus is free
   Jamulus is Open Source and the usage shall be free for everyone. The barriers to use Jamulus should be as low as possible to give everyone the chance to try it out and have fun. The server lists and the registered servers are intended for everyone to find a place to jam together, find new friends, have fun and maybe create a band or even a community. It is not desired to add any password protection to Jamulus.

6. Documentation/Acknowledgements
   Each new feature or bug fix must be documented in the ChangeLog. If a new contributor/translator adds code to the Jamulus project, he/she should be added to the contributor/translator list in the About dialog of the Jamulus software.

7. Merging Pull Requests
   The git master branch is protected so that at least two reviews must be done before the pull request can be merge. If a pull request received at least two positive reviews, any of the main developers can initiate the merge.

[ann0see]

Source code consistency

Good point. Do you follow a specific (official) style or a style guide? I'd suggest to add a file named something like "Contributing" which explains how to contribute and a link from https://sourceforge.net/p/llcon/discussion/developerforum/thread/69f1ecfd90/#811f to this file.

[corrados]

I just added the section "Jamulus is free" in my initial post.

[Erioldoesdesign]

Hey there! do you have any thoughts/plans for designer contributions? from a UI, UX, Usertesting/research or generally, visual pov? curious to see how I can support a designer that wants to contribute :)

[corrados]

As mentioned in my initial post: "Here is how I have managed the Jamulus project so far". Reading through a lot of forum posts it seems to me that some of the points are too restrictive and block further evolution of the Jamulus as its getting more and more popular. Most of the items are questionable. E.g.:

• People want IPv6, TCP, Port Audio, removing QT, etc., which are fundamental changes to the core source code of Jamulus. I was very restrictive to not violate item 1 (stability). Maybe we should allow more stability risks and allow more fundamental changes to the core software. So item 1 should be changed.

• People want more social features and other big features in Jamulus. So item 2 should be removed completely from the list. discussed further

• We have a lot of developers working on the Jamulus source code. Adjusting all the code contributions to the existing source code style is a lot of work and wasts too much time. So item 4 should be removed to make it easier to contribute code to Jamulus. So item 4 has to be overthought an a consistent code style/style guide added.

• We have many requests for adding passwords, blocking servers, kick out users from a server, etc. To fulfill these requests, item 5 should be removed. Item 5 should be re-interpreted

Edits by @ann0see (2020-01-29)

[gene96817]

The original principles are basically correct.
There are some new requirements that need to be accommodated, e.g. IPv6.

Keeping Jamulus free is very good. I encourage building a community with servers open to all.
Scheduling a closed rehearsal is a practical necessity for effectiveness. We need to walk the balance between a closed rehearsal and a jamming space open to all. We should encourage more sharing of servers (to see higher utilization).

Encouraging private servers goes in the opposite direction. Many musicians cannot install and manage a private server. For the long term development of a community, it would be sad to see more and more jam sessions disappear from public view. It is already strange so see so many empty servers.

[corrados]

@ann0see Since you have the rights to edit all posts, please feel free to update my initial post with the new agreements. Thanks.

[hoffie]

* People want more social features and other big features in Jamulus. So item 2 should be removed completely from the list.

I think one should be careful to keep Jamulus maintainable by not adding too much nice-to-have features which could also be implemented outside of Jamulus. Social features may be very helpful, but they may also carry a larger burden (e.g. user databases, proper authentication, password resets, uniqueu IDs, whatever).

* We have a lot of developers working on the Jamulus source code. Adjusting all the code contributions to the existing source code style is a lot of work and wasts too much time. So item 4 should be removed to make it easier to contribute code to Jamulus.

Hm, personally I am not a fan of the spacing within brackets which is currently required. However, as a new contributor who has never worked with a larger C++ project and Qt before, I was very pleased to see a really consistent code base. I think it would help mantainability to stick to a strict coding style. Maybe linters can be used to remove the purden of you maintainers to check the coding style manually (#901).

* We have many requests for adding passwords, blocking servers, kick out users from a server, etc. To fulfill these requests, item 5 should be removed.

I love this change because the status quo can be hard to "sell" to groups who need privacy. This is especially true with younger choirs/children. I like the intermediate approach by @ann0see's eduMode branch. Maybe something more official / integrated can be done in the future.

[pljones]

• People want more social features and other big features in Jamulus. So item 2 should be removed completely from the list.

I think one should be careful to keep Jamulus maintainable by not adding too much nice-to-have features which could also be implemented outside of Jamulus. Social features may be very helpful, but they may also carry a larger burden (e.g. user databases, proper authentication, password resets, uniqueu IDs, whatever).

One approach could be to set up a "Jamulus (Official) Discord" and have on demand creation of, say, geography-related rooms, genre-related rooms, etc. With Discord "roles", "put out a shout" in "Heavy Rock" for "@drummers in Western Europe" or in "US West Coast" for "@guitarist for a bit of psychedelia", or whatever.

That would still mean having Discord maintenance, of course - but all social forums need that.

• We have a lot of developers working on the Jamulus source code. Adjusting all the code contributions to the existing source code style is a lot of work and wasts too much time. So item 4 should be removed to make it easier to contribute code to Jamulus.

Hm, personally I am not a fan of the spacing within brackets which is currently required. However, as a new contributor who has never worked with a larger C++ project and Qt before, I was very pleased to see a really consistent code base. I think it would help mantainability to stick to a strict coding style. Maybe linters can be used to remove the purden of you maintainers to check the coding style manually (#901).

Absolutely agree. Style consistency improves maintainability - it also means a contributor is "listening first, not just hearing", reading what's already there and understanding it.

• We have many requests for adding passwords, blocking servers, kick out users from a server, etc. To fulfill these requests, item 5 should be removed.

I love this change because the status quo can be hard to "sell" to groups who need privacy. This is especially true with younger choirs/children. I like the intermediate approach by @ann0see's eduMode branch. Maybe something more official / integrated can be done in the future.

A build option like the headless and nosound ones might be one approach: by default and as distributed, Jamulus is open. But because it is open, it allows an easy approach to a more closed, private experience. It's still within the spirit of openness by not excluding those with different needs.

The limiting factor would be maintainability. Point 2 should remain overriding.

[pljones]

Things I hear a lot of requests for:

• Easier multi-channel set up
  The current need for multiple profiles that require manual editing of shortcuts puts this out of reach of many users' abilities. They may be quite happy with a hardware multi-channel mixer but trying to set up Windows, MacOS -- or even any of the multitude of Linux desktops -- to run the client with different profiles isn't what they call ease of use
• Related to the above, easy routing of audio from outside Jamulus
  Many people don't just want hardware audio in/out. They want to include their external inputs with some other source, like a backing track from their DAW. Basically the same as the first point but more "in the box", including on Windows "I want to play an MP3 into Jamulus".

Neither of these is "core". Both of them are "easily done" using external software. And, indeed, without substantial work, likely to stay that way. I just wanted them mentioned as "commonly requested features that violate the existing principles"...

[ann0see]

Agree. Can you open an issue on that or continue discussion in "Add protection for private servers"?

[ann0see]

I think the problem with this is that corrados has forked jamulussoftware/jamulus and therefore corrados/jamulus exists again (but without the issues).

[corrados]

I have removed my fork now. Do you still get the 404?

[pljones]

Seems okay now.