In November of 2019, a survey by Tidelift and the New Stack reported that over 84% of software developers consider themselves to be active open source contributors. The size of contributions has only grown since then, and each open source Project Manager who’s maintaining an ongoing project appreciates the help.
But despite the widespread act of contribution, it can still be unclear exactly how to contribute to open source projects.
While each project is unique, a lot of the same patterns occur across open source file repositories. A first step in getting to know those patterns is completing your first open source contribution on a project you know.
However taking that first step can be a struggle. To give you some more clarity, this article provides a guide to open source contributions – in particular, how to make contributions to the TinyMCE open source project on GitHub.
Why contribute to open source
When you make a contribution, you’re not simply correcting an error – you’re giving something valuable to a community of developers. This is the greatest advantage of open source.
Your contribution can help to speed development worldwide by solving a problem in a project, or helping it to mature at a faster pace. Your contribution could offer a novel way to solve a problem, which when adopted, could help a large scale business advance and innovate more quickly than they would have working on their own.
Now multiply that one instance by the number of developers who contribute to open source worldwide, and you have an idea of why open source contributions matter.
Why contribute to TinyMCE? It’s always been open source
The TinyMCE rich text editor has been an open source project since 2004. As a project, it’s grown to become the world’s most popular open source WYSIWYG. Over time, Tiny has also grown in its knowledge and experience of open source, and how to maintain an open source project.
We’re always seeking novel ways to invite interested contributors to check out the project, and have their work incorporated into the WYSIWYG.
As a long term open source software, we have an established community who can provide support to new contributors. This makes TinyMCE an ideal place to start working on open source.
Where you can find the TinyMCE open source project
The entire project is divided into different repositories:
- The Core editor
- Angular Integration
- React Integration
- Vue Integration
- The TinyMCE documentation
- Different TinyMCE Demos
Depending on your expertise and experience, there are a variety of different places where you can provide a solution, or address a bug.
What you need to contribute to open source
Experience with version control is a requirement, because open source has used some form of version control since it became widespread. Most projects are hosted on some kind of version control based repository: GitHub, BitBucket, GitLab, and AWS CodeCommit for instance.
Having an understanding of the essential git commands: git clone, git pull, and git push can also help, as does learning to stash and reset.
There are two further things contributors need to understand:
- There will be a review process, involving suggestions from developers
Be prepared to adjust your contribution as the maintainers review your suggested change.
- Open source projects are interconnected, and this means changes in one area could disrupt another
That's why point #1 is so important – the contribution may need adjustment to prevent disruption to another part of the project source code.
How to contribute to TinyMCE
The best place to start is the Contributor guide, and to read the Code of Conduct. Then check the issues section of the TinyMCE repository, and jump over to the Pull Requests section. That’ll give you an idea of the pattern of checking out any issues, working on solving a problem, and then how Pull Requests are returned for review.
Any contributors who make a change, and then work to have it merged, receive credit in the TinyMCE changelog, updated for each release.
As an example, the following procedure walks through making a change to the Contributor guide (to demonstrate the process).
Make a clone of the repository
Forking from an established project is a common open source practice.
- Head to the tinymce repository on GitHub
- Click on the green Code button in the upper right of the GitHub interface
- Copy the URL – either in HTTPS or SSH format
- Run the
git clonecommand with the copied URL in a terminal window or bash shell
If you run the git branch command after the clone process finishes, the first branch you see when you run the git branch command is named develop.
Create a new branch named for what you want to contribute, followed by a forward slash, and then the file affected by your change, or the issue number your change will fix. Here’s some example branch names:
- editing/CONTRIBUTION.md
- feature/Issue#1234
- fix/issue#1122
When you finish making the changes, the contribute guide describes the different tests you can run to see how your work impacts the project:
- CI test scripts
- Dev test scripts
- Running a subset of test scripts
The reason why tests are available is to ensure your contribution has not caused a break in any part of the code. Adding your tests ensures that the bug you're creating a fix for will be caught if it surfaces again, and proves your solution fixes the bug without adding further problems.
When testing is complete, use git add to add your changed files, and git commit to create a meaningful commit message. For example:
# Commit Message Title: Feature or Fix
## Why this change is needed
* Dot points to explain why the change is needed
Issues affected:#1234- Write the commit message in Markdown, since GitHub is able to parse it effectively.
- Push your commit up with the
git push --set-upstream origin <branch-name>command. - Navigate back to the repository in your browser, and make a pull request.
- Tag any TinyMCE devs you can see who have worked on the file you just adjusted – this can also help get your review checked more quickly.
Contributing to open source documentation
When making a contribution, if your change affects TinyMCE, and that change appears in the docs as an instruction, note, description, or similar, it’s also a benefit to the community if you also update the TinyMCE documentation.
If your aim is to work on the docs and make a change or an improvement, the process is the same as contributing to the TinyMCE source:
- Fork the TinyMCE documentation repository
- Write or edit the documentation
- Commit your change, and write a commit message following the same pattern noted in the above How-to section
- Reach out to the documentation team if you have a question.
Contributing to TinyMCE integrations
If you’re using one of TinyMCEs integrations, and you’d like to make a change to one of the TinyMCE integration repositories, the process is again similar to making a change to the main repository or the documentation.
There is one essential first step to take, before contributing to a framework integration. That is, test your bug and see if it can be replicated in a TinyMCE fiddle. Completing this step helps to identify where the bug actually comes from – ie. TinyMCE, or the framework.
Reporting open source bugs
If you find a bug in TinyMCE, and it has some impact on your work in the rich text editor, please report it. It’s easy to assume that the bug has happened to others, and that someone will eventually say something. But that’s not always true.
It’s better to report a bug you’re facing, because in maintenance practice, the more often an error appears, the higher priority rating it receives. Higher priority bugs are fixed faster.
When reporting bugs, it’s also ideal to include steps to replicate. This helps TinyMCE developers to more quickly identify where the problem lies, and start working on fixing it. Bugs are frustrating, make no mistake.
Including information about what happened before the bug, and any steps to replicate it are the last things that come to mind when things just won’t work. However, taking a second to capture and communicate this information can get results and doing so is an act of good open source citizenship.
Next steps to take in open source
Acting with good open source citizenship in mind makes a world of difference when contributing to open source. Communication is text based from start to finish in the majority of open source projects, and therefore it’s not difficult to misunderstand the meaning behind review comments without a voice.
When it comes to working in open source, it’s important to assume positive intent. Project maintainers have a responsibility to add improvements that benefit the project and all the people who use it. This is why you may be asked to make an adjustment to your solution.
Maintainers are grateful for the attention you’re paying them and their work by looking closely, finding a bug to fix, and updating any documentation.
If you need any further support and information on how to contribute to open source, particularly TinyMCE, check in with the TinyMCE discussion space, or take a look through the current, reported issues listed in the TinyMCE repository.
