github

Contribution Guidelines for YorubaName Codebase

This post provides bite-sized information that should help with the onboarding process for anyone who wants to contribute to the YorubaName dictionary project.

The skills needed to work on the YorubaName codebase are quite varied. This makes it possible for a diverse set of people with a wide range of technical skills to be able to join in the project: from developers/designers, UI/UX experts, to enthusiastic users and language lovers. This post provides the basic steps for all these types of people to get started.

Want to Contribute? Where to start?

Getting involved in the project is super easy.

Your first action point is to read the General Information README. It contains project-wide information that should be known to anyone working with the YorubaName codebase. Reading this would help provide clarity regarding the lay of the land and how different aspects of the codebase fit together.

The rest of the post explores the more specific guidelines.

Contributing as a developer to the Dashboard Application

The Dashboard application is a stand alone JavaScript application built with AngularJS. So if you are a JavaScript developer with some AngularJs chops, then this is where you may want to start:

  1. Clone and/or Fork the Dashboard application at https://github.com/Yorubaname/yorubaname-dashboard
  2. To understand how to run the application, go through the README at https://github.com/Yorubaname/yorubaname-dashboard/blob/master/README.md
  3. Ready to start coding? Then check the issue tracker at https://github.com/Yorubaname/yorubaname-dashboard/issues for a list of things you can start working on right away. Feel free to ask questions regarding the issues you are interested in working on in the issue tracker.
  4. If you have any questions regarding the project or the code base, feel free to drop by our gitter room at https://gitter.im/yorubaname-dictionary/dev, we would be eager answer your questions.

Contributing as a developer to the Core Website Application

The core of the dictionary and the website are written in Java using Spring boot. ElasticSearch is also used to power the search. So if you are comfortable with programming in Java and its ecosystem (or maybe you want to learn some more), this is where to start:

  1. Clone and/or Fork the Website application at https://github.com/Yorubaname/yorubaname-website
  2. To understand how to run the application, go through the README at https://github.com/Yorubaname/yorubaname-website/blob/master/README.md
  3. Ready to start coding? Then check the issue tracker at https://github.com/Yorubaname/yorubaname-website/issues for list of things you can start working on. Feel free to ask questions regarding the issues you are interested in working on in the issue tracker.
  4. If you have any questions regarding the project or the code base, feel free to drop by our gitter room at https://gitter.im/yorubaname-dictionary/dev, we would be eager answer your questions.

Contributing as a UX/UI designer

With the codebase of applications now on GitHub, someone with UX/UI experience can also easily see how the site is built and contribute in improving the user experience of the application. As a UX/UI expert the following steps should help in getting started:

  1. Read the general Information README here https://github.com/Yorubaname/general-information
  2. Explore the dictionary at http://www.yorubaname.com, and if you have any UI/UX suggestions then create an issue at https://github.com/Yorubaname/yorubaname-website/issues explaining the UX/UI improvements you have to suggest. Make sure to tag the issue with the UI/UX label.
  3. …OR: Peruse open issues with the UI/UX label in the Website Issue Tracker and Dashboard Issue Tracker and join in the conversation.

Contributing as a SEO expert

If you have expertise around SEO optimisation, then your ideas are also welcome. You are free to take a peek into the code base, and contribute your ideas on how to improve the SEO. You can either:

  1. Go to the GitHub issue tracker for the respective repository, and add issues explaining the changes you would suggest that would improve the SEO
    or
  2. If you know your way around code, clone and/or fork the codebase and create pull requests around SEO improvements.

Even if you are not a developer/designer/UI/UX expert, you can still contribute! The beauty of moving the development of the dictionary to GitHub is that it allows users to easily help shape the features that are built into the dictionary.

Contributing as a User

The codebase is not the only thing that is now on GitHub: our issue trackers, available in the form of the GitHub issues, can be found in the repositories. This is where we collect all bugs and feature requests that will be built into the dictionary. So if you encounter any bug or have any idea on how to improve the dictionary at www.yorubaname.com, then:

  1. Go to the GitHub issue tracker for the Website and the Dashboard, and add issues explaining the feature you want to see added to the dictionary. The developers will do their very best in building it.

So there you have it! Hopefully the information outlined should help make the process of getting started a lot easier.

Webinar for developers

If you’re still not quite sure, do not despair… To further aid people who would like to contribute to the project we are putting together a webinar on the 23rd of July targeted specifically towards developers where I will be:

  1. explaining how the different parts of the application fit together,
  2. how to setup the application on a local machine,
  3. how to get started writing code and contributing.

More details regarding the webinar can be found here. Register for free using this Google Form.

You should also connect with us on our social media channels: on Facebook here and on Twitter here.

Codebase now on GitHub!

One of the things we highlighted after the beta launch of Yorubaname.com was our desire to move the development of the YorubaName dictionary more into the public domain. In the post ‘What is in a Beta‘, I mentioned that moving forward, we would like to have both the project’s backlog and codebase accessible to the general public. This would empower whosoever is interested to be able to contribute to the building of what is fast growing to be the largest dictionary of Yorùbá names on the internet.

Today, I am happy to announce that we have done exactly that. The codebase that powers both the YorubaName.com website and YorubaName dashboard application can now be found on GitHub (https://github.com/Yorubaname) where you’ll have access to 3 repositories:

  1. The General-information: this contains basic general information needed to get started contributing to the project.
  2. The Yorubaname-dashboard: this contains the codebase for the dashboard application.
  3. The Yorubaname-website: this contains the codebase for the core dictionary and the website

With the codebase now on GitHub, we hope that the development effort behind the YorubaName dictionary, which started off in February 2015, and has been carried by four volunteer developers, will now grow to attract even more people willing to contribute expertise around software development to the project.

The development story: how it all started.

The development story of the YorubaName dictionary started off last year. It was kickstarted by an email I sent Kola Tubosun on a Friday, the 9th of January 2015.

The Yorùbá Name project had bobbed into my consciousness, though I can’t remember exactly how. If I were to guess, I would say it was via Twitter. I remember digging a little deeper into what the project was about and what it aimed to achieve and saying to myself: this would be something I would like to help bring to life.

So I got in touch with Kọ́lá, letting him know I would be interested in joining forces towards the building of the YorubaName dictionary. We exchanged a couple of emails, and by Monday, 12th of January 2015, while the fund raising drive was beginning to garner full speed on Indiegogo, we got working on our first task: setting up a prelaunch page for the project on www.yorubaname.com

Screenshot of the first landing page

Screenshot of the first landing page

Kọ́lá already knew Koko Godswill, a web/graphics designer who was also willing to volunteer and contribute to the project. He is largely responsible for the current look and feel of the dictionary. Not only did he help with the website, he has also worked a great deal towards meeting our various graphic design needs, most notably during the countdown to launch in February 2016 (See #YNLaunch).

But Koko was not to be the only person contributing. By February 2015, we got another contributor in the person of Esther Olatunde. She has helped tremendously in various ways, especially the setting up and the running of our blog at blog.yorubaname.com. We also had Luis from Brazil/UK who prepared a few mock-up wireframes on which we based earlier deliberations.

Then in April, Tola Odumosu got on board. He wrote about his motivation for volunteering here. Tola contributed substantial code to what later became the dashboard application which our lexicographers use to manage the name entries in the dictionary.

And thus from January 2015, Koko, Esther, Tola and myself were the developers who volunteered alongside Kola and the lexicography team to build the beta version of YorubaName.com released in February 2016. We were 4 technical people, located in different parts of the world: I was based in the Netherlands, Esther was contributing from Ghana, and Koko and Tola in Nigeria. We worked in our spare time towards the same goal and in a little over 12 months we were able to build a beta version of the dictionary, which at the time of writing has grown to contain over three thousand Yorùbá names.

The road ahead for the dev team

The current version of the YorubaName dictionary was made possible by the contribution of a handful of people. But now that we have opened up the codebase for more people to potentially get involved, the question is: what could be achieved next?

There is still a lot to be built. We have lots of interesting ideas and features yet to be implemented: from a ‘name finder’ feature – a tool to assist expecting parents in finding the perfect Yorùbá name for their children – to text-to-speech, to making the website more Wiki-like. We also plan on adding offline capabilities (especially for the dashboard application), improving the search experience, mobile optimisation etc.

So if you have a strong skill set in software development and you also happen to be passionate about culture and language, then the YorubaName project is something you would want to get involved with. Do not hesitate to get in touch on project@yorubaname.com. You can also, right away, fork the project on GitHub and let us start building this dictionary together!