I've recently contributed to TinaCMS and would like to share my experience with you. Generally contributing in development is when you take part of a project and add your own code to the code base. When using git this mostly happens in form of a pull request (PR) or otherwise known as merge request (MR).

In this article I assume you are already familiar with git and your choice of programming language. I will walk you through the code I've already successfully contributed and that's using JavaScript.

What to consider before contributing

When to contribute

So generally it's always good to contribute to a project because you will always learn from it. But it's also time consuming so you should decide if it's worth your time. If you are using an open source project yourself and you found some bug, you should definitely go for it and try to fix it yourself, this will probably speed things up. Also you can use contributions to gain some attraction and show off your skills to a company, especially if you are interested in a job.

Respect the rules

Normally most open source products that actually want you to contribute have some contribution guidelines. You will probably find those either on their website or in a file called CONTRIBUTING.md . In the case of TinaCMS you will find them in their docs.

You will find instructions that tell you how to report bugs, how to suggest enhancements, how to write documentation, how to add tests, how to contribute code and last but not least how the whole project is structured. This depends on the project, some have very detailed rules, some are more open and some don't have any at all.

Read those guidelines carefully and respect them because it can be very embarrassing when you try to submit your first code changes and everybody is like "Why did you do this? Why didn't you do it like we did?".

How to open a pull request on Github

Github is for sure the most known platform to host git projects besides Gitlab or Bitbucket. On Github you will first have to fork a project. Forking is simply a process where the project you are forking is duplicated under your own account. You can then clone it as usual.

As you can see I've already forked this project on my private account, so for demo purpose I will do it on another account.

Right after cloning I suggest to add the source (or upstream) as a remote:

git remote add source git@github.com:USERNAME/REPO.git

That way you can always run a simple git pull source master to update your clone.

Add your code

I will not go into detail on this one because this depends 100% on the change you are going to make. I just recommend to open a new feature branch via

git checkout -b feature/my-feature-branch

and to push it via

git push --set-upstream origin feature/my-feature-branch

Open a new Pull Request

When you are done coding and you made sure the project is still working, existing tests are still passing, the linter is not complaining and you have precompiled everything if necessary you should submit your changes to the original repository as a new Pull Request. Go to your clone or better said to your fork of the repository, switch to your feature branch and click on the New pull request button.

In this example I didn't change anything so it says There isn't anything to compare, but here your code changes compared to the original branch will be listed.

When you get to the next step you will have to describe your pull request briefly. Just explain what you did and why you made these changes. If you were not sure about certain things during development you can also ask questions here.

This is not a final step, you can still push changes to your branch and they will automatically show up in this pull request. It's also common practice to open a new pull request as soon as you start working on something, so others know that someone is already working on a feature or a bug.

Dealing with the pipeline

After you've submitted your pull request chances are that the owner of the original project has set up a pipeline for each branch. Your code changes will run through this pipeline where they are tested for certain things. If the pipeline fails it will probably tell you some lines of code that fail and why they fail. Go to your branch, fix them, push the changes and wait for the pipeline again.

This is how a failed pipeline looked after I made my changes

In this case the pipeline failed but it wasn't even my fault. When you go through the command line listed in the failed check you will find an error in the last one:

lerna ERR! npm run build stderr: /home/runner/work/tinacms/tinacms/packages/@tinacms/scripts/bin/scripts.js:35 throw err ^ Error: /home/runner/work/tinacms/tinacms/packages/gatsby-tinacms-json/src/index.ts(18,30): semantic error TS2307: Cannot find module 'gatsby-tinacms-git'.

This was caused by their setup because I didn't have access to certain servers. Something they already knew and quickly resolved on their own. Not a big deal.

Merge conflicts

When you are working on your feature it could happen that changes also happen to the master meanwhile. That will probably cause some merge conflicts. In order to speed things up you should try to keep your branch conflict free and merge master every now and then and resolve upcoming conflicts.

You are not alone

Creating a new pull request doesn't mean you have to solve everything by yourself. You can also use it as a primer to get started with a certain problem. Prepare things, try to solve parts of it, ask questions. Project owners will be thankful because you save them time and money, they are always happy to see new pull requests and interest in their project. Also everybody can commit to your pull request, as you can see here.

After I started the pull request and added my code changes there were still things to do in order to fulfill the pipelines requirements, some others fixed those.

Small PRs also solve a problem

If you are unexperienced with PRs or programming at all, you can also start by opening pull requests for small things. You can fix small bugs, typos, add documentation, explain things, add comments, fix the linter, add rules to the linter, improve the projects infrastructure and so on. You can also keep an eye on a projects issue tracker and see if you can solve some problems listed there.

Merging your changes

When you are done with all that you have to wait until some member of the project is going to merge your PR, as you will probably not have the rights to do so. If your changes are merged this doesn't necessary mean that they are already available in the package. At TinaCMS they release new versions every monday, so you will have to wait for it or install your PR directly meanwhile.

Receiving all the fame

I just pushed a very small bugfix but I've again learned something from it, especially because TinaCMS was built with Typescript and I am not using Typescript that often. Also I didn't know there is a bot to add contributors to the project. I am now listed on the project's contributors list and that made me quite happy.

Also my name was listed on the next Release notes: