An introduction to Github.com: the Matomo project
What is github.com?
One can give many definition of github.com, a social network for developers, a platform/website to collaborate among people, a drive mainly for code deposit. This is what it is. A website on which you can access to files dropped by others and on which you can contribute to those files/projects.
The major psychological thing to get, is that the main concept of the platform is that it is suitable to use the Git technology. Git, is a technology which is about versioning. So to say, it allows you to create different versions of your work in order
to go back to previous versions, work with others and so on and so forth. Git is a Free software technology released under the GPLv2 license: https://en.wikipedia.org/wiki/Git.
Github.com has been purchased by Microsoft in 2018. As you can imagine it is raising a lot of questions, I guess developers are still waiting to see how this platform will evolve in the
near future due to this acquisition. There are competitors platform but Github.com is the most popular.
Matomo and Github.com
Github.com has been the platform that the Matomo is using in order to develop the project since the beginning. That's probably the reason why they decided not to change once Microsoft purchased it. Will it be the case in the future... we don't know.
Here is the page of the Matomo project:
Everyone can create an account on Github.com. Once the project created, one can create repositories which are "sub-projects".
Why is Matomo putting all its projects on a platform such as Github.com?
Well that's the whole point of open source and Free software projects. The idea is to show transparently how the software/script are coded, where the data are going, who is working on the project, what are the evolution of the project, discussing with the community. It is all about transparency.
As you can see it is a major difference compared to proprietary technologies such as Google Analytics. To make it simple proprietary technologies are black boxes, Open Source/Free software are the total opposite.
An introduction to Matomo repositories
As previously mentioned repositories are sub-projects. Matomo is a big software composed of many plugins, in fact each feature within Matomo is a plugin. Some of them require a very specific expertise, so that's the reason why you have many here with different developers who have access to some projects.
Note that the rules may be different as well from a repository to another, for example some repository can be issued with a license and some others with another.
Example: Matomo for WordPress is a WordPress plugin... we cannot really say that it is part of Matomo because some people may need it, some others not, same thing for the Matomo Android SDK and so on and so forth.
People
It represents the people who are involved within the project or at least the people who decided to have their name publicly displayed. That's a great place on which you can see the profiles who are working on the development of the project and see their curriculum AND the different projects they are involved on Github. Compared to other social network places, in general they tend to be here not to make business but to collaborate and work on the scientific/passion aspects, so clearly not a place to start recruiting or spamming. Some of them will clearly show who they are some others will keep a level of privacy by using a pseudonym:
Let's get within a repository
Here is what a repository look like:
Code
The code part is let's say, the drive, the place hosting all the files of the project. When you have a Github account you can upload any kind of files here, either an html file if you would like to host/work on a website, a Python script, a pdf document etc. So nothing complicated it. It is just the files composing the project. In general at the bottom of this page you find some instructions coming from a file named readme.md (.md stands for markdown, it is one way to write some texts about documentation):
There are two terms that you can find on this page that you may find hard to understand, so let's explain them:
- branch: it is kind of a version of the project. The possibility for an individual or a group of people to work on a separate part of the project, typically, the development of a new feature and then to decide after some time to merge it with the main
branch of the project.
- commit: that's the creation of a version of a project.
- pull: that's the possibility to export the project in order to set it on your local computer.
- push: that's the possibility to send your project on Github.
Issues
Issues are written by anyone who would like to submit a ticket to the Matomo team. Those tickets can be very diverse (it is not only bug related, it can also be dealing with internal processes), they are categorized according to some labels:answered: the answer to this issue has been already given somewhere else like in the forum, through the professional support if it is a premium feature. Typically here it is waiting for a team member to close those issues and that those tickets
are not tickets anymore.
Better processes: those tickets are mainly for internal use. As previously mentioned Github.com is the place that the Matomo team is using in order to work, so this part is mainly not related to the software
itself but about how the team is working.
Bug: probably the place you want to investigate if there is something strange that you can see within your Matomo. The idea here is to see if the issue you are facing has already been documented.
c: Accessibility: this part is related to users who may not be able to see things properly.
c: APIs: all issues related to the Matomo API and it the APIs of the plugins.
c: Custom Dimensions: a special label for the issues related to the custom dimension plugin.
c: Design / UI: tickets related to the way the reports are shown within Matomo.
c: Documentation: it mostly relates to a need for additional documentation. So to say explaining how a feature within Matomo is working.
c: i18n: issues related to the way Matomo is translating some information.
c: Marketplace: improvement requests for the Matomo marketplace.
c: New plugin: those tickets relate to the creation of new plugins. So to say what the community is expecting for new features.
c: Onboarding: it is about how to make things better when people just start to use Matomo, like recognizing automatically the type of website.
c: Performance: everything which deal with how to make Matomo faster, mainly for database performance.
c: Platform: it is about any improvement of the Matomo core software but not be noticable to users (so only on the technical end)
c: Privacy: everything which deal about improving the privacy aspect of Matomo.
c: Security: all about how to make Matomo securer.
c: Tests & QA: is about how to automated test in order to debug.
c: Tracking: everything dealing with how to send data to Matomo.
c: Usability: a bit like accessibility but more feature oriented. Accessibility is when the color contrast of a button is so low that people with poor Eyesight can't read the text properly. Usability is when it is not clear what the button does
c: Website matomo.org: For issues related to the matomo.org website.
Can't reproduce (yet): issues are getting reported by the community, but the Matomo team needs to be able to reproduce them in order to validate them as proper tickets
to work on.
Critical: indicate what the team needs to work on as a priority.
dependencies: it means that those tickets will have some consequences on others.
Do not close: Pull requests with this label won't be marked as stale by the Close Stale Issues action.
duplicate: it is an information label in order to say that this ticket has already been written somewhere else.
Easier debugging: for issues that makes troubleshooting issues easier to fix.
Enhancement: those are for big improvements within Matomo. Typically what most people are looking for.
Help wanted: a very interesting label. Those are issues that can be fixed by people who don't know Matomo well. So if someone wants to contribute to Matomo, they should look at those first. And if someone new is hired to work on Matomo they will
look into these first to become familiar with the project.
invalid: it indicates that it is not really an issue, so it should be removed.
Likely a server config issue: issues related to a server configuration.
Major: it indicates the severity or impact or benefit of an issue which is much higher than normal but not critical.
Needs Review: the issue has been fixed but need a code review.
not-in-changelog: For issues or pull requests that should not be included in our release changelog on matomo.org.
Potential Bug: something that might be a bug, but can't be reproduced (yet).
Pull Request WIP: WIP stands for Work In Progress, so the team is currently working on it.
Regression: indicates a feature used to work in a certain way but it no longer does even though it should.
RFC: Request For Comments where the author is looking for feedback.
Stability: For issues that make Matomo more stable to run for sys admins.
Stale for long: The label used by the Close Stale Issues action.
Stale: The label used by the Close Stale Issues action.
Task: Indicates an issue is neither a feature nor a bug and it's purely a "technical" change.
trackingspam: for issues related to receiving tracking requests from spammers and bots.
Waiting for user feedback: Indicates the Matomo team is waiting for feedback from the author or other users.
wontfix: If you can reproduce this issue, please reopen the issue or create a new one describing it.
worksforme: the issue cannot be reproduced and things work as intended.
Milestones
A great place to have a look at in order to see the vision of the Matomo team:
on this page you can see the version that they are currently working on, their progress, their short term priorities to as the long term priorities.
New issue
This feature allow you to create a ticket within the Github.com system:
and for each of them, the Matomo team is guiding you in order to write the more descriptive issue. That's really important in order to ensure that your issue will be taken into consideration.
Pull requests
It refers to what the team recently worked on.
Actions
This is the list of things which happened over the life of the project on Github.com