I designed and prototyped an artificial life framework for simulation (or games) in Java 8. When I was happy with what I had made and how it could be used the first thing I thought about was making it open source. Actually getting to the point where anyone can use or contribute to it was a right nightmare (had no doc at all)!
I think my open source framework would be really useful to students or to anyone going open source. Here is why:
- JALSE is on GitHub: this means you really have to learn git (I'd like to know why any new project wouldn't use git). Source control systems seem like a unnecessary thing when you're working solo but as a team its 101. GitHub makes it easy by having everything visually available to you (and it's pretty). JALSE GitHub
- JALSE is built by gradle: It really doesn't matter what you use to build as long as it makes your life easier (and for me that's gradle). It's clean and easy to read what's happening and it's the best parts of Ant, Ivy and Maven! My build script not only downloads all the dependencies, builds and tests; it can also create an Eclipse project, sign jars and release them to Maven central. Building JALSE
- JALSE uses Travis-CI: Whenever I make a change (or get a pull request) that change is built, tested and analysed for its code coverage. This means whenever anyone hands me code I know it compiles, doesn't break tests and hasn't polluted my source base (any more than I already do). I can focus on the logic and standard of their work (and so can they). What it looks like when I get a pull request | Previous failing build
- JALSE has issue tracking: We use issues for everything - questions, enhancements, bugs, feature requests. This results in a no blame culture for issue creation. If you want to know what's about to happen (or what you can work on) check the issue. This is another thing that isn't required for a solo project but unless you want to work the same feature as me or spend hours investigating what I just did - your employer has an issue tracker. JALSE Issues | Bugs and questions?
- JALSE is fully documented: This is key for you not having to have a face to face whenever someone thinks what you've done is cool. How do I get your release? How do I raise a bug? How do I contribute? How do I use feature X (yeah that complicated one)? It shouldn't be mayhem if you ever wanted a vacation. JALSE Wiki | Class diagram
- JALSE is fully javadoc'd (code doc): Knowing what a method, class or package is meant to do functionally vs what it actually does is quite important. A wiki wont have every single method covered but you know what you're using if it's doc'd in the code. Also it's much easier to find. JALSE API docs
- JALSE is licensed: This seems like a really tiny point but it's a big deal. The difference between a licensed library you can use for non-commercial vs also commercial is a big one from a companies perspective. So if a licence is missing or isn't clear - it's likely to cost you users. What my licence means
- JALSE is on Maven central: When you fulfil a set of criteria (above) you can apply for a repo at Sonatype OSSRH (OSS Repository Hosting). This gets synced with Maven central and means anyone can grab your library without needing to know where you host your code. JALSE is as easy to get as the JUnit! Getting a JALSE release | Getting your stuff on central
I think JALSE is doing open source right and stands as a good example of a project being managed well in 2015. We're looking for more contributors (code and ideas) but that's not what I want this post to be about. I want you to look at all of the services I've integrated to give you a professional library people want to contribute to and I want to tell you all I spent was £2.59 (JALSE.org was on sale). All of the above technologies are free for open source software (and most also for commercial use). Why not mock up your own code quality concious GitHub repo and show it to your next future employer (lots of you can code well but I make sure the people around me do too).
Want to chat about your project? PM me or for JALSE chat use Gitter.
Good luck!
tldr: Creating good doc is important and so are defined processes (makes life easier for all). Use JALSE as an example for your project doc + integration. Travis-CI integation | Code coverage integration | Licensing | Communication | Accessible for users