DEV Community: Vandolf Estrellado

GitHub stars is ruining my mental health. Need help/advice.

Vandolf Estrellado — Tue, 01 Mar 2022 02:02:11 +0000

Hi, my name is Vandolf and I have some internal problems. With disasters happening all around the world for the past several years, I really have nothing to complain about. I know that this internal "problem" is laughable and makes me really ashamed that it is even affecting me at all. Yet, for the past six months, this "thing" has been eating me up inside. It has been affecting my social and professional life.

If you'd rather read about real problems happening around the world, please click away. Otherwise, stay and you might get some amusement out of it if nothing else.

The thing is, I know hardships. I was born and raised in the slums of the Philippines. I know what real hunger is like. I know the feeling of helplessness and acceptance of having no future. I was luckily able to immigrate into the US. I am now living in Hawaii with my wife, son, dogs, and cat with a view of mountains and oceans. I take nothing for granted. I am truly grateful for the life that Android made possible.

❓ So, why is GitHub stars bothering me so much? It's just a number, right?

This article is NOT an attempt to get stars.

I really just want to discuss what I have been "suffering" from for the past half year. I will NOT provide links to the projects or mention any names. I want this article to be on topic. I want it to be anonymous, yet personal.

Please don't dig deeper. I will not answer any comments about specifics. Though, feel free to send me a DM. Maybe we can talk privately. You can even tell me how pathetic I am.

GitHub stars. How much does it matter?

There have been many articles and discussions that have been written about this topic. This article is not about the value of stars but rather a personal story about it.

Anyways, here are some of the good stuff that I’ve read…

TLDR; The opinion is split. To some, stars are just publicly visible bookmarks. To others, stars are shining beacons that signal to others of the amazing quality of a project. Or a mix of both.

I think of stars as what they are typically associated with. A sign of quality. Something to look up to. Beautiful. Shining bright..

So WTF is my problem?

I'll cut to the chase. I will not beat around the bush. I'll say things how they are, the way I see it.

My problem is that my project that I have spent thousands of hours on for the past three years has less stars than another very new project that contains just a fraction of what I have already built.

I know right? What a BIG "problem"! I mean O.M.G.! I can't believe this is happening! It is atrocious! WILD! Crazy! I mean, forget about a global pandemic, a potential world war, increasing divide between rich and poor, and other social and economic problems. This is something we have to discuss right now 🔥 🔥 🔥

I know how insane it is for me to even be writing this article. It is difficult for me to write because the community can literally crucify me for writing about such a trivial matter. I can imagine you reading this and laughing and maybe even annoyed. I am writing this and laughing too. I have some mental issues. I know. I 100% agree with you. I am a pretty down-to-earth guy, except when it comes to this project.

Why is this a problem?

I keep asking myself that question. I cannot seem to come to a conclusion that would allow me to move on with my life. Hence, why I'm writing this article.

For the sake of this article, I will refer to the other project's author as "Red". I want to keep Red's identity anonymous so please do not dig deeper. The thing is, I like Red. Under different circumstances, I would have loved to be friends with Red. If Red ever reads this article, please know that I have nothing personal against you. I hope that we can be friends in the future once all of this is behind us (or behind me because this is probably just all in my head). I feel very petty about the way that I feel about this situation.

My project and Red's project are both trying to solve the same problem. The problem is so specific and niche that our solutions will most likely end up being the same, to some extent. I hope that our APIs stay as different as possible so that we can give the community different options.

Anyways, here is a table that compares my project to Red's project.

	My project	Red's project
Stars	~290	~350
Forks	~20	~15
Watchers	~7	~2
Contributors	~4	~4
Issues	~50 (only 1 bug)	<5
Downloads	~10k/month in JitPack	???
Age	~3 years	~0.5 years
Features	~80%	~10%
Language support	Kotlin & Java	Kotlin
Documentation	High	Low (relative)
Tests	None yet (in roadmap)	Fair

What can explain the gap in stars?

Looking at the table, it might seem like my project not having tests (yet) could be the sole reason why I'm losing in star count. After all, why would anyone want to use something that has no tests. Someone in Reddit pointed out the lack of tests. I gave an explanation about the value of tests in relation to the type of system under test. The cost of a single person writing tests for an unstable, humongous API in its early stages. Anyways, this article is not about explaining the varying importance of tests vs documentation. We can discuss this in the comments if you are interested. Tests are coming soon.

What I truly believe is the reason for the gap in stars is the ever growing amount self-promotional posts Red has done for the project.

	Me	Red
Twitter	0 (0 followers)	~10+ (1300+ followers and growing)
Reddit in total	1	~10
Most popular subreddit	1	~4
Featured in weekly mailing lists	2	2
Paid to be featured in weekly mailing lists	0	1-2
Dev.to	1	1
Medium	1	0
Hacker news	1	1

I put a lot of love and effort in every single post that I do. I think the post reactions speaks for itself.

	Me	Red
Total upvotes in Reddit	~320	~295
Single Reddit post with most upvotes	~320	~110
Single Reddit post with most awards	~9	~4
Reactions in Dev.to	~17	~5

I'm thinking quality vs quantity. I'm with the former. Red seems to be with the latter.

❓ Is Red a spammer or am I just not promoting enough?

I actually think that Red is technically a spammer because Red has exceeded the 50% max self-promotion rule in the subreddit Red posts in. Red has posted 4 self-promotional posts and only 2 non-promotional posts (one of them is questionable and could also count as self-promotion). I could technically get 2-3 of Red's Reddit posts removed due to rule violation if I just report it. Tempting, but I really don't want to be a hater. I want to like Red. I know that I like Red, especially if it were not for this whole ordeal.

What is bothering me the most?

I made a rule/principle for myself. The rule is that I will not promote the project more than once on any website. Ever. This way, other projects from other people can get the chance to surface. I think that if everyone that was/is maintaining an OSS were to do what Red is doing, then developer communities will just be filled with spam and self-promotional BS.

What Red is doing is literally the opposite of what I believe people should do. I don't want to spam the community. I truly believe that "good software will sell itself once enough people have seen it". I believe that once a project has reached a certain amount of stars/visits, then it is time to stop promoting it and let the community do that work organically.

I'm sure there are plenty of folks that would consider me stupid for saying these things. That's why I see articles on "how to get 1k+ stars in GitHub". Every article like that has comments that say "stars are not important". However, they clearly are. It is the easiest metric for everyone to use in order to measure the "quality" and popularity of a project.

Is this all in my head or is it also in Red's head?

I might be crazy and just imagining things but I think Red is in a competition with me.

Red promoted their project for the first time when it was less than a month old. Red quickly gained 100+ stars with the first few promotions.

It took me 5 months to catch up to Red's star count. At that point our projects both had about ⭐️ 250 stars. Those 5 months were the most demoralizing months of my life as a developer.

❓ How could someone promote their one-months' work and get a barrage of instant recognition when I spent years working on mine?

Then, recently, my project got a burst of traffic from LinkedIn. I don't know how. I can't find any posts about my project in LinkedIn. It was organic growth! Possibly someone else recognizing my work. In just two days, my project finally surpassed Red's project in stars by 25. I thought to myself "great job. You were right. Good software will sell itself. You don't have to promote it anymore."

The following day, I saw a lot of commits from Red's project. Red made a bunch of BS changes and packaged it into the holy grail of releases. The "V1.0 Release"!!! The day after that, Red made another post on Reddit, which garnered some attention. Red probably also paid to be on the next popular mailing list issue.

Red's efforts managed to propel their star count by ~50 stars ahead of mine. From my point of view, Red panicked and/or was very offended that my project managed to surpass theirs in star count. That led to Red scrambling, trying to figure out how to immediately "fix the situation".

In my head, there is absolutely no way that this could be coincidence! Just no way. Red even made remarks in the Reddit post and README that clearly references my project.

The thing is, I know Red's project inside and out. After all, we are trying to solve the same problems. The changes that Red made within the span of the project's half-year lifetime was not substantial at all (in comparison to my changes). I'm confident to say that the amount of changes Red made so far only amounts up to 1-2 of my bigger commits in my project. I think that Red is simply using new releases as an excuse to do a promotion. The amount of activity in the repo always spikes up before Red does a promotion. In between, there is almost no activity. I am the only person that can actually call Red out on this IMO unethical behavior. No one really checks these things ya know?

Why does this all bother me so much?

I genuinely just want to give back to the community. I don't want the community to be misled and use (IMO) a lesser project just because it is getting much more heavily promoted. Actually, Red's project is inherently incorrect because of one big fatal flaw in its design. So the fact that Red's project has more stars than mine absolutely bothers me.

I am sure that Red's project would be useful to a lot of folks that would benefit from Red's particular public facing API design. However, I don't think that most folks should choose Red's project over mine. If only everyone knew about both.

I also want to believe that good software will promote itself. However, that theory is clearly losing to the theory of advertising. I am seeing that advertising beats quality. I don't want to believe it but it is what I am observing.

If Red had not come along or if Red's project was truly deserving of the recognition, then I wouldn't even care about stars at all. I promise. If my project has 50 stars today (instead of almost 300), I would feel very accomplished. However, the fact that there is another project that is literally years behind mine but has more stars eats me up on the inside. It just makes me feel like all of the work, love, and tears that I spent does not matter.

Red is just getting started

Red is now promoting another new open source project. The thing is that I know an existing project that already does the same exact thing in the same exact way. It is still being maintained regularly. I don't think Red cares. Red has amassed a bunch of followers that is growing every day. Red does not mention similar/identical projects. Red knows that Red can get more stars because of the ability to shamelessly self-promote. In just a few days, Red's new project is close to getting 100 stars.

I'm making a prediction here. This new open source project that Red is building will be integrated into Red's first open source project. Red will then be able to promote the two projects at the same time in a single post. Two birds, one stone. Genius really.

I respect Red for his marketing abilities. I truly do. However, just because you have the ability to do something, does not mean that you should do it. I believe this is true especially for open source where most maintainers get "paid" in "star count". It can demoralize folks like me that do not have social media presence nor the audacity to promote regularly.

What is my nightmare?

The worst thing that I can think of in relation to all of this is for Red's project to exponentially outgrow my project in terms of stars.

I believe that if Red's project has 1,000+ stars whereas mine has less than 300, then most people will not end up using my work at all. All of the hard work and passion that I spent for years, invalidated all because of the number of stars someone else managed to attain from over-promotion.

How is this all affecting me personally and professionally?

I am unable to stop thinking about how many stars my project has vs Red's project. It's become an obsession.

I go to sleep, wake up, do my work, have lunch, spend time with my wife and son, walk my dogs, play with the cat, have an outing in a beautiful beach, eat good food, etc. Not a single time for the past half year had I not thought about GitHub stars in all of those daily activities I mentioned.

I don't want to be like this. I want to be the best person that I can be for my family and even co-workers. People are depending on me. Even though I do perform my role in all fronts, I am simply not mentally, emotionally, and spiritually 100% present. All because of this whole stupid BS that I cannot believe that I have allowed to take over me.

If you read this entire post, you can clearly see that I am obsessed with my project and with Red's project. I take it all too seriously and too personally. I am too competitive when I really don't want to be. It's not who I am. I am not competitive. At least I thought I wasn't...

Before Red came along, I was just enjoying working on my project. Then this war of GitHub stars was ignited. I felt that I had no choice but to participate...

I need your help/advice.

So, time for me to ask questions. I could continue ranting but I'm sure I have already lost most of my readers at this point.

❓ When it comes to self-promotions, how much or how often is too much?
❓ Is my rule of "post only once per site forever" stupid or admirable or both?
❓ Should I accept and play into the GitHub stars game? Should I attempt to build up a large social media presence and followers under the pretense of being helpful in order to advance my own agendas?
❓ Should I just not ever look at stars?
❓ Should I abandon, archive, or delete my project?
❓ Is Red doing anything wrong?
❓ From a scale of 1 to 10, how pathetic am I to be writing this article?
❓ How would you handle this if you were faced with a similar situation?
❓ Any other advice you are willing to give?

Does extensive documentation do more harm than good?

Vandolf Estrellado — Mon, 03 Jan 2022 00:01:33 +0000

I feel like I tend to write too much documentation in code, PR descriptions, PR comments, JIRA tickets, markdown files, etc. If I can write documentation on it, then you bet that I am doing it 😆 There are few exceptions where I don't write documentation such as self-explanatory, 1-liner code... I think I do it because I don't like people asking questions. Really anti-social behavior 😊 Some may say that I have obsessive-compulsive disorder.

Warning! The following GIFs may cause siezures as they have been sped up to meet maximum file size limits.

I'm writing documentation in code, extensively...

Useful? Not useful? Who cares? No one? Readable? Beautiful?

I'm writing howto pages for all APIs, functions, and entities in the library...

Cool? Or insane? Or cool but a waste of time?

It looks like this in the mobile GitHub app...

Tell me it's not pretty... Tell me! (Please don't tell me).

I'm using GitHub Pages as a free website for my hard work on my documentation...

Can't really turn down a free domain and 1-click theme changes 😄

I'm writing really long responses in my open source discussion pages, issues, and PRs...

Because I want to make my collaborators feel heard and appreciated.

These insane tendencies carry over to my professional life. I write really thorough, detailed JIRA tickets, Slack messages, architectural docs, engineering notes, to a point of insanity. Typically, when I post my response to people at work, they usually don't have any follow up questions. They expect that if they ask Vandolf a question, he will answer that question and give every bit of context related to it with links to supporting documents and visual aid (GIFs and videos with callouts) when needed. It is probably starting to annoy some people at work despite them publicly giving me praise for it.

I don't have a GIF for this part because I don't want to get fired 🔥

It also carries over to my personal life, which I will not discuss here...

So... Lately, I've been wondering if I'm wasting time being so... thorough and a bit of a perfectionist. I spend more time documenting than actually writing code. I guess it reduces the bus factor and at the same time makes me super dispensable because everything I know is documented. So they can just fire me and let someone else take the lead 😁 The upside to all of this is that I am able to completely disconnect from work. I can completely discard all work-related thought (may that be private or open source) because I know that when I resume, I would not have lost any context due to my poor memory.

Thoughts?

DO I HAVE A PROBLEM? Is something wrong with me? Am I trying too hard? Being too anal? Should I calm down? Relax? Find something better to do? Why am I even doing all of this? Is there such a thing as too much documentation? Do people even read documentation? How do you interact with people like me? Is it tiring for you? Does it make you not want to talk to me because then you will feel committed to reading a blog as a response to every single one of your questions?

I spent 3 years writing an Android Contacts API in Kotlin with Java interop. What I’ve learned…

Vandolf Estrellado — Thu, 04 Nov 2021 23:13:30 +0000

Hi, my name is Vandolf and I have a problem. I get addicted and obsessed about certain things. It spirals out of control, very quickly. Once I set my sights on something, I don’t stop until I finish it, even if it takes years. Sounds like addiction… It is.

Before I know it, I've spent three years working on private repositories building something no one knows about. Then, I make it public and write an article about it thinking that it will blow people's minds. Then get shocked that the repo has less than 100 unique visitors in the first month because I think that it will just magically get discovered by everyone...

Does this sound relatable to you? Probably not, right? I think I'm insane in some levels. If you are interested in the Contacts API library I've built or the insanity I'm going through, keep reading!

I'll split this article in two sections.

The Contacts API that I've built. 🔥
The mistakes I made and lessons I learned from writing "open source" code, privately, for three years. 🤦‍♂️

If you are not interested in the first section, I recommend at least reading the second. You might learn something from the mistakes I've made, and hopefully avoid making them yourself!

I'm actually a bit hesitant and nervous about posting this as my first article here. I have no reputation here. No one knows me. I'm just a random stranger. However, I know that doing things that are only within my comfort zone will not get me anywhere. So, I'm pushing myself to publish this article 😰

I hope to make connections, and maybe even friends, in this community ❤️

The Contacts API that I've built.

First, here is the GitHub repo; https://github.com/vestrel00/contacts-android

Please take a look at it and let me know what you think?

The oldest commit in the repo is 2 years old. However, I have another private repo that has the 3 year old commits. I'm not lying! 😁

Exactly a month ago from today, I have made public the previously private repo and published an article in Medium introducing my Contacts API library to the ether. The article covers the history of Contacts in Android since Android API 1 to API 5 (Eclair) all the way to API 31. It talks about how, for over a decade, there has not been a single open source library that abstracts away all of the complexities of Android's Contacts Provider and ContactsContract. The community has been forced to deal with ContentProviders and cursors, spending a plethora of hours of trying to figure out how to do even the simplest things. Then it goes through an overview of the Contacts API library that I've built and how you can use it to create your own full-fledged Contacts app in Kotlin and/or Java.

A hypothetical, but probable, story.

I won't repeat myself or copy-paste things so I'll take a different approach in this article. I'll go through how a normal person might use the native Contacts application and show code snippets on how you can implement those use cases using Contacts API, Reborn. To make things easier to follow, let's go through a hypothetical day of someone named Vandolf.

One day, Vandolf takes his phone and opens up the Contacts app. He's bored so he decides to look through the contacts he has saved over the years.

val contacts = Contacts(context)
    .broadQuery()
    .include(Fields.Contact.DisplayNamePrimary)
    .orderBy(
        ContactsFields.Options.Starred.desc(),
        ContactsFields.DisplayNamePrimary.asc(ignoreCase = true)
    )
    .limit(20)
    .offset(0)
    .find()

He sees favorites at the top of the list (which includes his wife, son, dogs, and cat) followed by non-favorites, ordered by the contact display name. Vandolf scrolls down to see more.

val contacts = Contacts(context)
    .broadQuery()
    ...
    .limit(20)
    .offset(20)
    .find()

One of his high school friends popped up. Curious about his ancient friends, he types a name in the search field.

val friends = Contacts(context)
    .broadQuery()
    ...
    .whereAnyContactDataPartiallyMatches("henry")
    .find()

He sees a bunch of contacts with the name "Henry". Determining that it is in fact the same Henry, he decides to link them all together into a single contact.

listOfHenries.link(Contacts(context))

He then searches for Victor and finds that he only has one contact with that name. He knows that he has 3 friends named Victor so he opens up that contact and discovers that the Contacts Provider mistakenly combined 3 different Victors into a single contact. Facepalming, he decides to unlink the Victors into 3 separate contacts.

victor.unlink(Contacts(context))

Continuing his mindless quest of browsing his contacts, he looks through his contacts one account at a time.

contactsApi
    .accounts()
    .query()
    .find()
    .forEach { account ->
        val contactsFromAccount = contactsApi
            .broadQuery()
            ...
            .accounts(account)
            .find()
    }

Then he realized that he only wants to see contacts from all of his Google accounts.

val contactsFromGoogleAccounts = contactsApi
    .broadQuery()
    ...
    .accounts(
        contactsApi
            .accounts()
            .query()
            .withTypes("com.google")
            .find()
    )
    .find()

Not finding what he is looking for, he decides to browse contacts by label (group membership).

contactsApi
    .groups()
    .query()
    .find()
    .forEach { group ->
        val contactsInGroup = contactsApi
            .broadQuery()
            .groups(group)
            .find()
    }

Unable to find "that person", he decides to do an advanced search.

val thatPerson = Contacts(context)
    .query()
    ...
    .where {
        (Name.GivenName startsWith "Jose") and
        (Email.Address { endsWith("gmail.com") or endsWith("hotmail.com") }) and
        (Address.Country equalToIgnoreCase "US") and
        (Event { (Date lessThan Date().toWhereString()) and (Type equalTo Event.Type.BIRTHDAY) }) and
        (Contact.Options.Starred equalTo true) and
        (Nickname.Name equalToIgnoreCase "Dota 2 Pro") and
        (Organization.Company `in` listOf("uber", "eats", "door", "dash")) and
        (Note.Note.isNotNullOrEmpty())
    }
    .find()
    .firstOrNull()

Vandolf got tired of browsing. He decides to make a new contact for his ol' imaginary friend.

val contactsApi = Contacts(context)
val accountToAddContactTo = Account("vestrel00@pixar.com", "com.pixar")

val insertResult = contactsApi
    .insert()
    .forAccount(accountToAddContactTo)
    .rawContact {
        setName {
            givenName = "Buzz"
            familyName = "Lightyear"
        }
        setNickname {
            name = "Buzz"
        }
        setOrganization {
            title = "Space Toy"
            company = "Pixar"
        }
        addPhone {
            number = "(555) 555-5555"
            type = Phone.Type.CUSTOM
            label = "Fake Number"
        }
        setSipAddress {
            sipAddress = "sip:buzz.lightyear@pixar.com"
        }
        addEmail {
            address = "buzz.lightyear@pixar.com"
            type = Email.Type.WORK
        }
        addEmail {
            address = "buzz@lightyear.net"
            type = Email.Type.HOME
        }
        addAddress {
            formattedAddress = "1200 Park Ave"
            type = Address.Type.WORK
        }
        addIm {
            data = "buzzlightyear@skype.com"
            protocol = Im.Protocol.SKYPE
        }
        addWebsite {
            url = "https://www.pixar.com"
        }
        addWebsite {
            url = "https://www.disney.com"
        }
        addEvent {
            date = EventDate.from(year = 1995, month = 10, dayOfMonth = 22)
            type = Event.Type.BIRTHDAY
        }
        addRelation {
            name = "Childhood friend"
            type = Relation.Type.CUSTOM
            label = "Imaginary Friend"
        }
        groupMemberships.addAll(
            contactsApi
                .groups()
                .query()
                .accounts(accountToAddContactTo)
                .where {
                    (Favorites equalTo true) or
                    (Title contains "friend")
                }
                .find()
                .toGroupMemberships()
        )
        setNote {
            note = "The best toy in the world!"
        }
    }
    .commit()

val olImaginaryFriend = insertResult.contacts(contactsApi).first()

Of course, Vandolf adds a photo of good ol'Buzz.

fun onClickPhoto(activity: Activity) {
    activity.selectPhoto()
}

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    onPhotoPicked(requestCode, resultCode, data,
        photoBitmapPicked = { bitmap ->
            olImaginaryFriend.setPhoto(contactsApi, bitmap)
        },
        photoUriPicked = { uri ->
            val bitmap = MediaStore.Images.Media.getBitmap(contentResolver, uri)
            olImaginaryFriend.setPhoto(contactsApi, bitmap)
        }
    )
}

Vandolf then decides to make some changes to his new contact.

val updateResult = contactsApi
    .update()
    .contacts(olImaginaryFriend.mutableCopy {
        setNickname {
            name = "The Buzz"
        }
        removeAllPhones()
        removeWebsite(websites().first { it.url?.contains("disney") == true })
        events().first().apply {
            type = Event.Type.ANNIVERSARY
        }
        setNote {
            note = "The best toy in the world - EVER."
        }
    })
    .commit()

He also sets the first email to be the default/primary email.

olImaginaryFriend.emails().first().setAsDefault()

Once Vandolf has finished his business in the toilet, where this entire story has been taking place 😮, he decides that the whole exercise was stupid and deletes his olImaginaryFriend.

val deleteResult = contactsApi
    .delete()
    .contacts(olImaginaryFriend)
    .commit()

I'll stop the story here. This article is getting too long and I've probably lost 95% of the readers at this point.

That story barely scratched the surface of the library.

There are a lot more APIs in the library that remains untold. The story would be too long if I wanted to showcase everything that the library can do. I’d have to write a novel!

One thing I will mention here as an extra is that all of the functions I’ve shown in the story do not handle permissions and also does the work on the call-site thread. I left those out for brevity and to show that the APIs are framework-agnostic. Anyways, the library provides Kotlin coroutine extensions for all core functions to handle permissions and execute work outside of the UI thread.

// Use the *WithPermission extensions to ensure permissions are granted prior to querying.
// Use the *WithContext or *Async extensions to execute the operation outside the UI thread.

launch {
    val contacts = Contacts(context)
        .queryWithPermission()
        ...
        .findWithContext()

    val deferredResult = Contacts(context)
        .insertWithPermission()
        ...
        .commitAsync()
    val result = deferredResult.await()
}

Extensions for Kotlin Flow and RxJava are also in the v1 roadmap, which includes APIs for listening to Contacts database changes.

All APIs in the library are optimized.

Some other APIs or util functions out there typically perform one internal database query per contact returned. They do this to fetch the data per contact. This means that if there are 1,000 matching contacts, then an extra 1,000 internal database queries are performed! This is not cool!

To address this issue, the query APIs provided in the Contacts, Reborn library, perform only at least two and at most six or seven internal database queries no matter how many contacts are matched! Even if there are 100,000 contacts matched, the library will only perform two to seven internal database queries (depending on your query parameters).

Of course, if you don't want to fetch all hundreds of thousands of contacts, the query APIs support pagination with limit and offset functions 😎

Cancellations are also supported! To cancel a query amid execution,

.find { returnTrueIfQueryShouldBeCancelled() }

The find function optionally takes in a function that, if it returns true, will cancel query processing as soon as possible. The function is called numerous times during query processing to check if processing should stop or continue. This gives you the option to cancel the query.

This is useful when used in multi-threaded environments. One scenario where this would be commonly used is when performing queries as the user types a search text. You are able to cancel the current query when the user enters new text.

For example, to automatically cancel the query inside a Kotlin coroutine when the coroutine is cancelled,

launch {
    withContext(coroutineContext) {
        val contacts = query.find { !isActive }
    }
    // Or, using the coroutine extensions in the async module...
    val contacts = query.findWithContext()
}

All core APIs are framework-agnostic and works well with Java and Kotlin

The core APIs in the core module does not and will not force you to use things you don’t want. As a matter of fact, the only dependency the core module has is the standard Kotlin lib! Use whatever Java or Kotlin permissions or threading library you want. The extensions are optional and are there for convenience.

I also made sure that all core functions and entities are interoperable with Java. So, if you were wondering why I’m using a semi-builder pattern instead of using named arguments with default values, that is why. I’ve also made some other intentional decisions about API design to ensure the best possible experience for both Kotlin and Java consumers without sacrificing Kotlin language standards. It is Kotlin-first, Java-second (with love and care).

Modules other than the core module are not guaranteed to be compatible with Java.

The library provides full documentation in code and with how-to pages. The project also has a vision and a roadmap.

Documentation and how-to guides are all available and linked in the repository. You can browse the Howto pages or visit the GitHub Pages. Both contain the same info but the GitHub pages are not guaranteed to be up-to-date. The GitHub wiki hosts the project roadmap. It contains all planned work and release schedules, which are organized using issues, milestones, and projects.

The mistakes I made and lessons I learned from writing "open source" code, privately, for three years.

For the past three years, I've had my head buried in the sand. I kept myself out of all social media. No Facebook. No Twitter. No Instagram. No Reddit. No Medium. No Dev.to. I got my world news from several news outlets. I'm subscribed to AndroidWeekly and KotlinWeekly to keep myself up-to-date in the world of Android, given that my entire career hinges on it.

For the most part, it was a great experience. By "it" I mean real life. We all know social media can be a detriment to one's health. I don't regret it at all. I can say with 100% confidence that I am healthier now because of it.

I have been working at a great company and spending time with my family. When I find free time, I work on this project.

However, now that I have made this passion project public, I'm coming to a stark realization that I should not have completely disconnected myself from everyone. At the very least, I should have kept myself active in the open source community that I'm attempting to be a part of.

Mistake #1 - Writing "open source" code, privately.

Do you see the paradox in that statement? Really, what was I thinking 🤦‍♂️. I know it's a classic mistake and I'm not the only one that has made this mistake. Some of you reading this may have also or is in the process of making this mistake.

First, it is useful to understand why people do this. Why I did this. For most, it's something along the lines of "I don't want to show it to others until it is done". While I can relate to that, for me, it was really about not having the time to participate in open source and collaborate.

In my mind, and I could be 100% wrong here given that this is the first library project that I encourage others to use, had I made it public from the beginning and successfully pulled in others to contribute, I would not have had the same flexibility and agility to build the API the way I wanted to. I would have had to convince other contributors that this is the way to go and spend time collaborating to come to the best possible solution. Collaboration takes time. To some, especially folks like me, it is a commitment. At the time, my son was just born and ever since then, finding time to do anything for myself has been very difficult.

The mistake that I made here is that I missed the whole point of open source. The very thing that I was trying to avoid because I had no time is the thing that makes something open source. It is as much about the collaboration than it is about the output. Me building something privately, then making it public does not suddenly make it open source. It just means that I built something and other people can see and use it now.

My code, even though it is public now, cannot be considered open source (even though the source is open).

Mistake #2 - Thinking that no one else in the world is building what I'm building.

Another classic mistake. My thought process here was that since no one has attempted to wrap the entirety of the ContactsContract for the last decade, why would anyone do it now? There are so many contacts management apps out there already. Surely, a simplified Contacts API is not in demand. No one needs it. No one is working on something like this except me 💥

While I knew deep down that this mindset was completely wrong, I lied to myself thinking that I must be the only one to discover this missing basic-but-critical component in mobile development. There are 6+ million Android devs in the world but I must be the only one that have scoured the internet searching for a simplified Contacts API so that I can use it for work...

Because of this mistake, I now wonder how many opportunities to collaborate with like-minded individuals have I missed?

Mistake #3 - Not participating in the open source community.

I claim that I want to contribute and be a part of the open source community. However, I don't even make the effort to contribute to the open source libraries I use on a daily basis for work (e.g. RxJava, Glide, etc) because I don't think I'm smart enough. So, I figured that one way I can participate in open source was to work in secret by myself for years and then promote my secret-made-public code as "open source". What a joke! It is a farce. 💩 💩 💩

I clearly misunderstood what open source is.

What I have now is a not-open-source-but-public repo. 😆

Anyways, because of my isolationism, I have no reputation in any developer communities even though I’ve been working for almost a decade now. This lack of reputation makes it extremely difficult to spread the word about stuff I want to share. For example, like most communities, the subreddit r/androiddev has a self-promotion rule that states that the maximum amount of posts you can do to promote your own creation is 50%. This is a big problem for me because up until less than a month ago, I didn’t even have a Reddit account!

I will not post things that I’m genuinely not interested in just so that I can game the system. I have really just been interested in this project for the past three years.

❓ Is that wrong?
❓ Is there room for people like me who zoom in on one thing, spend years on it, and share once they deem it presentable?
❓ Or are we living in a world of instant gratification where all you have to do is spend a few hours, days, or weeks on something and then proceed to market it?

One stroke of good luck I had was when my manager at the job I had four years ago encouraged (or maybe even forced?) the entire team to write dev articles, even while at work. I wrote Howto articles about dagger-android in Medium under the ProAndroidDev publication. The first ever article I wrote made it to issue #268 of AndroidWeekly! I did spend months on the accompanying GitHub project so it was nice to see my hard work get recognition. At the time, I didn’t really think much of it. The editors of ProAndroidDev did all the marketing for me. I told them that I had no Twitter account. No Reddit account. I didn’t even know what AndroidWeekly was. From this, I managed to gain some followers and enough of a rapport with the ProAndroidDev editors, albeit four years ago, to allow me to get my newest article published under their publication.

I have to keep in mind that having connections give you an incredible advantage that you can use as a platform to boost yourself up initially. It applies to everything. Landing your dream job. Meeting like-minded people. Getting a reservation at a restaurant (pre-COVID) that is always booked, let's say Dorsia? Most relevant to this article, having a reputation (or enough posts/karma) in forums such as r/androiddev allows you to self-promote when the time comes. A luxury that I currently do not have.

This leads me to the next mistake...

Mistake #4 - Hoping that people will magically discover what I've built without promoting it.

I truly believe that a "good software or product will sell itself". It is a common expression for a reason right?

❓ So, if my repo is not getting any traffic, then it must be because what I built sucks, right?

As I mentioned earlier in this article, I already published an article in Medium a month ago. That was it for my promotion. I submitted a link to the medium article and my repo once to AndroidWeekly and KotlinWeekly but to no avail. I even emailed the curators of those legendary mailing lists explaining the amount of work and love I put into this project and how I think others should know about it. They are not responding. I don't blame them. Why should they look at or respond to some random person with no reputation when they probably have to sift through hundreds, if not thousands, of submissions?

A month later, my repo has had less than 100 unique visitors (some of which are probably not even human). I'm not hunting for stars! I’m hunting for traffic. I sounded like an advertiser there... I don't know how else to say it. We all have to "advertise", at least a little bit in the beginning to kick things off. I feel that I owe it to myself and my family, for putting up with me sometimes spending a lot of time on this instead of with them, to get the repo looked at by enough human eyes to justify the amount of time that I've spent on it.

It just happens to be that the easiest way to know if the community thinks a project is good is based on the amount of stars divided by the amount of views. The star/view ratio provides repo owners a heuristic calculation of how many people find the repo useful versus those that see it and just click it away. I could be completely wrong here, in which case please leave a comment and let me know your thoughts about it?

I'm not trying to sell anything. I'm trying to help people solve their problems with anything related to Android Contacts management. I'm not going to get money from this. Will I get attention and fame? Maybe? I really don't want that, honestly. If that’s what I wanted, I would be doing things involving hot new stuff like Jetpack Compose instead of something that’s been around for over a decade.

I might be contradicting myself here but I really just want to make sure that other Android devs out there are aware that they no longer have to fear Contacts like I did. There is now a Jetpack-like component that is fully documented with Howto guides on everything they can think of. They no longer have to scour the internet to find something that does not exist.

At the end of it all, as long as I have truly helped a handful (and I mean less than five) of other devs out in the world, then I have no regrets. Maybe I'll get sincere emails from three people letting me know how much my work helped them? Regardless, I will continue working on the project until I deem it complete and all issues have been closed.

❓ BUT, how can others know the existence of the API I created if it does not appear on any search results in any search engines?

Luckily, this is a mistake that I can still fix, hopefully... And no, I will not fix it with money. I will not pay to be featured in any mailing lists or to appear at the top of search results. I want the community to decide if what I had built should be used by others or not.

So, I still think that "a good software or product will sell itself". However, I'll make a minor modification to that.

"A good software or product will sell itself, once enough people have seen it."

I will not spam the community. However, I will write genuine articles like this from time to time with new content I have not yet shared. By the way, this article took me around 10 hours to write, proof-read, rewrite, and repeat. I hope that the Dev.to community can consider that enough of a justification for this not to count as spam.

Mistake #5 - Answering ancient questions in StackOverflow using the APIs that I've built.

This one is tragic comedy. I was not aware about self-promotion rules in StackOverflow or dev forums in general. After all, I have just started participating in developer forums. But bliss cannot be used as an excuse!

Anyways, I always thought that I could answer all contacts-related questions in StackOverflow after making my library public. After all, most of us find questions and answers in StackOverflow. So what better way to make sure people know about my API than answering questions in the stack?

Excited and full of energy and determination, I began answering decade-old questions in the stack. I used a template for all the questions I answered. I did not save it, nor do I have access to them now, but I remember it being something like...

Android Contacts has just been Reborn! Using the Contacts, Reborn library, you no longer have to deal with the complexities of ContactsContract.

To answer your original question...

"(quote original question here)"

Using the Contacts, Reborn library...

In Java,
(insert code snippet of how to solve the problem in Java using my library)

In Kotlin,
(insert code snippet of how to solve the problem in Kotlin using my library)

There is a lot more that the Contacts, Reborn library can do. You can even build your own full-fledged contacts app with it!

It's probably not exactly that but it's the best that I can recall.

Anyways, after around ten hours of answering around 20-30 questions, I continued to answer more questions. However, when I tried to post an answer on October 8, I got the message saying something like "this account can no longer post answers". Then, I noticed that I had a message from the mods. It said that I violated self-promotion rules. So, they removed all of the answers I posted. All of that hard work, excitement, and determination, vanished into thin air. Gone. Just like that. It hurt. It really did. I was sad, furious, emotional. However, I understood that rules have to be followed even if I did not know them. Bliss is no excuse!

I took a screen recording of the message thread in my phone. Here is a screenshot of the message I got from the stack mods. I was too emotional at the time when I was reading it. In retrospect, I could have taken a different approach to handling the situation 😅

Again, in retrospect (reading it again now), I could have handled the situation differently. I could have still said what I had to say (that I'm hurt) but just try again and only answer a few questions instead of trying to answer all of them. I had over a hundred questions bookmarked and I was ready to spend tens of hours to answer them all!

So, I sent them a heartfelt reply and then deleted my account. On a side note, it takes 24 hours for an account to get deleted in the stack. It's probably there to give emotional folks like me some time to calm down after getting the well-deserved hammer. There is even a message, and I paraphrase, "we noticed you just received the ban hammer, calm down and reconsider deleting your account?"

I know you are curious to see the message I sent. Everyone loves a bit of drama, even if it isn't your favorite genre 😆. I consider this tragic comedy! I'll share it with you all. Only here in DEV.TO! Don't worry, it does not contain profanity or anything of the sort. It is not not-safe-for-work (double negative). Even though I was emotional, my head was leveled enough to avoid sending a self-career-ending reply 😌. I knew who I was talking to. I was talking to hard-working mods that have to sift through hundreds and thousands of posts and make hard decisions like this knowing that they will get backlash from individuals. I was talking to people that keep the stack community alive and well for everyone (including you and me) to find answers. I was taking to people that have helped me get to where I am now in life. Who am I to disrespect them? I can't. I won't.

Before I share a screenshot of my reply, please know the following.

I'm sharing this with you because I want to share my mistakes so you can avoid doing it yourself.
I am not trying to hurt the StackOverflow community. If anything, I’m trying to help the moderators by having folks read my story as a cautionary tale!
I respect, love, and admire, folks that are active in the StackOverflow community. I was just trying to be like them... but I failed.
I still use StackOverflow to get answers, anonymously for now. I hope to create an account once again, when I feel like I deserve it.

Without further ado, here is my reply...

Reading it now after almost a month, I can see my heightened emotions. I made several grammatical errors as I only proofread it once. I was well aware that I was emotional when writing that at the time. I am typically patient and I wait to do things until I'm level-headed. However, I intentionally decided to write that reply immediately because I wanted my emotions to come through. I wanted to show them how it affected me and probably folks that have and who will experience the same thing that I did. I knew that if I had waited even just an hour, I would not be able to write a reply that conveyed what I truly felt. I don't regret writing that reply the way it is written. I felt like it had to be written that way. Otherwise, I would be doing myself (and others like me) injustice.

I know for sure that I'm not the only one that went through this experience. Have you gone through this? How did you handle the situation? I'd love to know!

Thank you for reading!

Whether you read all of this article or just some parts of it, thank you ❤️ 💗 💕 💞 💘 💖

I give every bit of love and care to this project, including the articles I write about it. I would appreciate any feedback. What do you think about the library? Did you make the same mistakes I made? Do you agree with the lessons I've learned? Any other thoughts? I sprinkled in some questions throughout the article, care to share your thoughts on any of them?

P.S. I am working on a fun app that uses the library that I've built. It is already in a public repo. I still need to work on it a bit before I start ranting about it and getting others to contribute. I am excited about it though! This time, it will truly be "open source" ❤️