Contribution Guide

#1

I've recently gotten started with Axoloti, and am playing around with my board and patcher at least occasionally giddy with excitement :slight_smile: However, in the short time I've been able to use the system, I've noticed that there's a bit of rough edges here and there in the Patcher, f.e.

Trying to scratch my own itch, I went to have a look at the github repository. It's quite sizeable, and I wasn't able to orient myself particularly quickly.

Some Open Source projects (especially the larger ones) maintain something called a Contribution Guide, which usually contains informations for potential new developers regarding how to make code contributions, eg. which branches are used in the repository, formatting details, how to file issues etc. Another starting point is some documentation on how to get an environment set up for development, eg. git clone, <run package manager>, hack away, how to compile and use the changed code. None of the above needs to be particularly verbose, just the minimum to get something set up or at least to point in the right direction.

Some questions off the top of my head:

  • git branch usage, there's master, and experimental with more recent activity, and then a few more. Where am I supposed to find the latest code, make pull requests to etc?
  • what do I need to do to get a development environment set up? I haven't done desktop programming with native/java apps in years, mostly mobile, server & web, so I don't have an idea where to start. My immediate concern would be to fix some issues with the Patcher UI.
  • code organisation, there's a doc folder, but half of the content is in html and the markdown files don't seem to be particularly up to date.
  • roadmap? I saw a topic on this, there's a markdown file in the doc which hasn't been touched in a while, but there's stuff happening in the experimental branch which is difficult to correlate with anything. Is it just people working on their own stuff or is there some kind of coordinated effort, or at least an idea of what currently is being worked on or anything that would be scheduled for future releases.

And there's bound to be more stuff that could be covered, f.e. just by looking around at other OS projects and seeing if the content seems relevant. If someone has happened to get set up lately, I think it would be a great opportunity to write down some notes and contribute to some initial documentation.

I realise that all of the above sounds like a "heavy" activity and something difficult to maintain, but that's not really my intent or experience. Getting invested in the Axoloti means that I'm also invested in an active community, and helping people who can and want to develop just creates a positive feedback loop IME.

#2

not got a lot of time (always the problem, no? :slight_smile: ) so I'll just answer main questions for now.

id agree with most of your points, but yes, most refer to larger open source projects, when the coordination is essential, and also the 'maintenance' of documentation etc is important, and most importantly there are volunteers willing to do it.

master - is basically, current release plus essential bug fixes.. i.e. if we were to do a 'maintenance release' this is where it would come from

experimental - is where we (johannes and I) are working for the next release, assuming we dont find anything that goes horribly wrong, hence why experimental rather than dev
you'll also see a new chibios branch with johannes is doing, this once stable will be merged to experimental

.. so if its just small bug fixes, master would be a good place IF you know it doesn't jeopardise the branch with bugs.

dev environment, run platform_x/build.sh, this will get most things required.
for java dev you should use netbeans, since this is used for the dialogs etc, but other than that you can just run ant

docs , user guide is built dynamically from this forum... you can see this in build.xml, apart from that yeah, the docs are a bit dated :wink:

roadmap, its johannes project so if you want to do something contact him, he can let you know if its in line with what he wants to do, and also if other work is being done/considered that may clash with it. this is what i do.

yeah, I know , seem loose (hell, its not how i run commercial projects :wink:) , but its pretty common for small projects, where 'one man' has the main vision and drive, and others tend to dip in and out occasionally.

so, if you plan to do some dev, contact johannes with your ideas, then of course once you have spoken to him, you could update the documentation if you feel the desire :slight_smile:

#3

Hi, I decided to try to build the experimental branch and I hadn't done that in git before, so here's the sequence that's worked for me:

Just follow what's here: https://stackoverflow.com/a/72156
The only thing they don't mention is that at the end you want to re-run "git clone https://github.com/axoloti/axoloti.git"

These are the key steps in case that link goes down:

git clone https://github.com/axoloti/axoloti.git
cd axoloti/
git branch -a
git checkout origin/experimental
git checkout experimental
git branch
git clone https://github.com/axoloti/axoloti.git
git status

then build it:
./platform_linux/build.sh

Also, while I'm here, I got a failure running ant, I'm trying to fix it by upgrading JDK. Here's the key part of the output from ant:

-do-compile:
[javac] Compiling 673 source files to /home/enzo/axo6/axoloti/build/classes
[javac] javac: invalid target release: 1.8
[javac] Usage: javac
[javac] use -help for a list of possible options

BUILD FAILED
/home/enzo/axo6/axoloti/nbproject/build-impl.xml:911: The following error occurred while executing this line:
/home/enzo/axo6/axoloti/nbproject/build-impl.xml:261: Compile failed; see the compiler error output for details.

I believe this is because I had an outdated java development environment (was on 1.7, appears to need 1.8).
On Ubuntu 16.04 LTS, you have to do do this:
http://ubuntuhandbook.org/index.php/2015/01/install-openjdk-8-ubuntu-14-04-12-04-lts/

Updating JDK on to 1.8 for Ubuntu Linux
Here's the summary of key commands:

sudo add-apt-repository ppa:openjdk-r/ppa
sudo apt-get update
sudo apt-get install openjdk-8-jdk

sudo update-alternatives --config java
sudo update-alternatives --config javac

java -version

Let's try it again:
BUILD SUCCESSFUL
Total time: 8 seconds
DONE

#4

not sure why you are going thru all those steps...

all you need to do is:

git clone https://github.com/axoloti/axoloti.git
git checkout experimental

however, note... if you plan to make any contributions then you should fork the axoloti repo in GitHub, then it becomes:

git clone https://github.com/<your-github-username>/axoloti.git
git checkout experimental

this will allow you to push changes to the server, and then issue Pull Requests

note: then google how to setup upstream repos so that you can merge in changes from the axoloti/axoloti repo.

Im not sure where your getting the JDK 1.8 dependancy from, i cant see it in the ant or build scripts....
and originally I ran this with openJDK 1.7
*however as I pointed out in this thread , you'll need the Oracle JDK 8 for the java-fx / bundling stuff... so thats the one I have installed.

#5

git remote add upstream https://github.com/axoloti/axoloti.git

Great, so based on the above it'd be an easy PR to add that to the README