How to upload your first library to Open Source

Published in

inDrive.Tech

7 min readApr 14, 2022

Hello! My name is Roman Aimaletdinov, and I develop software for Android at inDriver. Today, I thought I would share with you what I have gleaned about how to open-source your project.

Preparing your project

The first thing to do before you release anything in Open Source is to make sure that the project contains no commercially sensitive information covered by your NDA:

1. Talk to your manager and get a verbal approval.

2. Create a private repository. Now we have to tweak it and make it public once everything looks good and all approvals are in hand.

Note: The best thing to do here is to copy and paste the relevant part of the project or module so that the Git history is overwritten. You must agree that it would not be cool if some curious history buffs managed to pull some business information out of your project.

3. Answer the following questions:

Does the code contain any sensitive data (passwords, tokens)?
Has the Git history been deleted?
Are you violating anyone’s copyright?
Does the solution in question use third-party fee-charging libraries?
Is there any business logic in the code for your project?
Are all the files required (maybe something should have been added to gitignore)?
Are there any endpoints in the network layer, any calls to the backend?
Is the code covered with comments in English?

4. Maybe, in your case, it would be a good idea to make a sample project where your solution would be used.

Note: In my personal opinion, the sample should be really simple, not using any third-party libraries. I’ll just say that again — it should be VERY simple.

If you add View Binding and a couple of other libraries that you are used to, you will make the project harder to understand for people who code differently. The emphasis should only be on your solution.

If you want to demonstrate different scenarios for using your library, it makes sense to make several sample projects. For example, one could be as simple as possible, while another might use a more sophisticated logic that works for those who already have the basics down.

5. Let’s say you have made sure that you’ve removed everything that was unnecessary, you’ve turned up no working endpoints, and everything looks good. Great! We get in touch with your security people, get official approvals from them and from the highest leader, within the scope required by your organization.

License

The next step is we go to your legal counsels and go over it together to find out which license suits you.

I advise you to carefully read the licenses, as some of them do not allow you to change the type of license in the future, which may bring you down.
You should remember that you might want to earn money from this solution in the future.

Licenses are a whole separate topic, so within the scope of this article I just want to alert you to some important, in my opinion, points. But I definitely advise you to read it through before publishing, rather than just inserting a license. And if suddenly the project takes off, you can change it. I liked this article, especially the list of links that the author provided at the end.

Liability

Bear in mind that if a business places its trust in your solution, it is depending on you. It will use the solution and expect you to update the repository periodically. It may also depend on your repository.

But let’s say you come up with something, but you’re not sure the solution will take off. Or that the project will be supported for a long time and responsibly. You wish to protect yourself from software developers’ anger and from direct claims by because your solution does something unexpected and inconsistent with the documentation. And as a result, they lose a lot of money due to errors in your repository.

To minimize the risks, I advise writing a disclaimer in the readme.md:

It all depends on you, your project, and the degree of your involvement in your open-source software. Such a disclaimer is important not because you want to absolve yourself of responsibility. But because if you are not sure that you will responsibly support the project — let the community know! Let them be ready to make their own assessment of the risks involved in using your solution. We are a polite community, and it is only right to warn your colleagues.

Documentation

You have probably already created the readme.md file. I would recommend that the following items be reflected in this file:

Name
Introduction (very short, just the gist)
Installation (here the Gradle version)
Intended purpose (explaining in plain language the reason for setting up this library)
Problems your library solves (points 1, 2, 3..)
Solution (how the library solved the problems)
Example
How to test it
Sample tests
License
Disclaimer

It turns out that your library should contain a large amount of information. For example, make sure to describe in detail how to install it. Write it in such a way that even a newb can handle it. Do not leave out anything that seems obvious to you. We all have different experiences and differing ability to assimilate new information. Provide the help needed to use your solution.

Perhaps there will be a lot of information. Then you will have to make several .md files that will link to each other.

Publication on JitPack

For some people, this may seem to be the absolute best part of the article: how to make sure that our code is included in .gradle in one line? That is, like this:

There are several options for how to do this. jFrog was once quite popular. You can also use the Mymavenrepo service which provides the ability to download and connect the plugin. There are other ways to deliver our code as well. But I will tell you here about jitpack.io.

This technique is very simple. I am sure that with this article as a guide, the process will take no more than half an hour (roughly, that is).

Let’s suppose the coding is already done, the documentation written, posted on GitHub, and approved by management. Now let’s do a few things:

1. Make the GitHub repository public (visible to everyone).

2. Register on jitpack.io via a GitHub account.

3. Now we need to prepare the code and configure build.gradle so that JitPack can build the artifact. The service has kindly prepared a sample project, based on which you can figure out what needs to be added to the project. But I will place some extra emphasis on this.

So, first we need to add to build.gradle:

Make sure you have:

And we configure:

The last thing to be added is this:

All the code above was taken from the example provided by the service. However, I will additionally show you the build.gradle of my project so that you can see how else it might look:

Well, actually, here’s my personal project, you can take a look at it and even put an asterisk there. I will talk about this separately in the future.

My JitPack did not get going right away. My mistake was that I didn’t have the publishinginstructions and themaven-publish plug-in. In the logs that the service provides, it said that it was not possible to build the artifact.

Update the version in theversion field and push. But that’s still not all. To trigger JitPack, you need to push git tag. In other words, we execute several commands in the terminal:

We will launch our first release, JitPack will trigger and create a build artifact on its own, and then generate a path where our library can be installed.

2. After registration, on your left, you will see a list of your open repositories. Choose the one that interests you:

A page with logs and the generated dependency path will open up. If your release fails to build an artifact, you can download the report and check what the problem is. Take a look at the sample project. Perhaps you missed something. If all is well, the report will be highlighted in green.

3. Well, and the last thing to do here is to insert instructions for installing your open-source project into your readme.md file. Please note that you can paste a link to a dynamically updated version in your readme file and the community will see a beautiful sight with a green or red fill color, depending on the success of the artifact creation process.

That’s it. Testing is the only one thing left for us to do now, but hopefully you know how to best do this without my help. Let’s do a quick recap now and briefly highlight the key points again:

Make the repository public.
Register on jitpack.io.
Configure build.gradle as shown in the examples.
Push the changes.
Push the new Git tag.
Look at jitpack.io to see if the artifact has been built.
Run the tests :)

Links