1

Hey Guys. I'd like to get some feedback about bringing several closed source packages to open source. It's a collection of separate but connected, indepent packages.

I'm an independent game developer. I've spent years building packages completely in Swift for the purpose of real time graphics simulation / video games.
You can check out my YouTube real quick to see what level of code these packages are at. I've coded everything from scratch in Swift and I'm only using a few libraries for hardware accelerated graphics, and image / sound decoding.

I intend to slowly begin modularizing my code into purpose built packages. All math types and associated operators/functions would go into GameMath for instance.

My code is clean, Swifty, and verbose. But my documentation is poor and there is no testing suite at all. I always intended to create performance tests but I just haven't had time or needed too yet.
I intend to go through each function and put something in for documentation. It won't be amazing but it'll be something. Most people will want tutorials anyway, which I'm willing to do if there's enough support or interest.

Now, as for my experience collaborating in open source goes... I have very little. I've worked for the man a few times and hated it, and I've mostly been solo.

To be perfectly honest I'm terrified. I'm not perfect and my code is not perfect. I've spent years and years on this and having someone tell me I suck and it was all a waste of time is gonna ruin my day, and that's how the internet is; I've decided to accept this possibility because many people have express interest in this code and I'm doing it to make them happy and broaden the use of Swift for gaming within the Swift community.

So knowing the above, what kind of tips can you guys offer me for progressing forward with my plan?
Are there things I should do to the code before making it public, besides a license and copyright? (it'll all be Appache 2.0)
Thanks! Any and all feedback would be helpful :hearts:

10 Likes
2

IME, of those you'd expect (guides, docs/refs), one of the most crucial pieces is a good read me. If I don't even know what I'm looking at, I wouldn't spend much time figuring it out. I'd want to at least get a feeling of what it's like using the project. Personally, I prefer short hands-on examples. They give me immediate, actionable work to understand the project, but just about anything will do.

The documentation can be pretty light since people don't really read source code until they're already invested, which may take a while. Though I hope that it grows over time–good documentation habits can save your future self, if not anybody else. Of those, at least focus on documenting user-facing APIs since that's what people most commonly look for (markdown works best since IDEs can pick that up). The same goes with the actual code.

Now, I'd be lying if I say I know how to take criticism, but one thing I learnt is that there are non-critical criticisms (this looks bad) and more critical ones (this isn't very idiomatic, try that instead?). I tend to focus on the more critical sides. I might still feel bad reading it, but hey, at least I learn a thing or two.

Remember that there are people who like your work, and this does look interesting!

On a more technical side, modularizing things tend to help so long as you don't overdo them. If they're going to always bump a version together, might as well put them together. While some projects separate things into multiple repos, I find "small projects" to be easier to manage with a single repo. SwiftPM supports multiple modules anyhow.

6 Likes
3

Firstly, it's great that you want to open-source your code! It's a communal good that benefits all other software developers (not necessarily just Swift developers, although we will especially benefit).

Documentation and testing are good development practices, regardless of whether the source code is publicly available, and it sounds like you recognise that. Documentation, especially for public APIs, helps developers learn how to use your library, and creates a behaviour contract which gives you freedom to change the details of the implementation. The extent to which you should document non-public APIs is somewhat up for debate and depends on the specific APIs. Personally, I tend to over-document those things, which can be just as bad as having too little documentation (if the docs become stale, they're effectively useless and can also lead to bugs).

Testing helps validate the correctness of your code, and gives assurances to people who might want to use your library that it does what it says on the tin.

It is a lot of work, though. It's no problem to make it an aspirational goal and even ask for help to get it done.

I wouldn't worry about it. Not to say that it won't happen, but I've been quite active in the Swift community since the beginning, and I've only ever seen well-intended discussions and comments about code which people volunteer to open-source. Nobody expects perfection - the compiler and standard library are not entirely bug-free (otherwise bugs.swift.org wouldn't exist), and really no large software engineering project is. You make your best effort, things continuously improve, it takes time.

You shouldn't have to put up with insults or harassment (if it does happen). If anybody doesn't like what you've created, they can use something else. If they want to take it in their own direction or make changes you disagree with, open-source code allows them to do that; they can fork the project and change it to suit their needs. You have a game, which shows that the code does something useful; therefore it has value.

Instead of worrying about criticism, look towards the good things that open-sourcing your code can bring, and focus on making it easier for contributors to add value (if you're accepting PRs). It can connect you with other developers who are interested in the same topics, and you can work together towards making all of those improvements that are difficult to manage on your own.

5 Likes
4

Yup! I'm separating things out, but packages will be dependent on other packages. There will be a single highest package most will use, but using the lower level packages will be there as an option too. For instance someone might want to use the math package but use their own rendering code or build their own engine. But good point, I'll be carful not to make packages that are needlessly small or obscure.

1 Like
5

Yup, I'm not terrible at it. My code is mostly verbose. I try to make the actual code obvious and I document things that I feel I'd get confused about later.
As an arbitrary example this code creates a float4x4 out of a quaternion thats rotated in degrees around an axis.

Matrix4<Float>(rotation: Quaternion(Degrees(-90), axis: .right))

While it takes up a lot of space, it's fairly obvious what it's doing just by looking at it. I've tried to write all my code like that. I never intended to do open source, but I try to write code as if someone is going to use it besides me, so I've fallen into a pattern of making the code something you read; It is the documentation.

I personally scroll through source code for discoverability. Sometimes I just command click an arbitrary swift function and start scrolling through the standard library for fun. I'd like users of these packages to be able to do the same.

This is where I've fallen short. I'll admit there are a few #warning("this is broken.") in my packages. Code I'm not suing but couldn't bring myself to remove.
But you're right, others could be interested in doing this. Writing tests can be fun if that's your goal. Performance tests in particular have a gaming like addiction. I think I'll outline a basic test suit so people have somewhere to start if they are interested in contributing.