Taxonomy Maintenance
Introduction
Taxonomies play a central role in Open Food Facts. Have a look at Taxonomies for more details.
If you want to help building, extending, translating and maintaining the taxonomies, a few options from simple to complicated, are listed here.
Just tell us
The most easy and quick way to contribute to the taxonomies, is to tell us about an issue, even if it is not related to taxonomies. If you see an ingredient that is not recognised, a category that is not translated or a NOVA-score that is not computed, it might be a taxonomy issue.
Tell us on Twitter with #openfoodfacts, in our Facebook channel, mail us on contact@openfoodfacts.org, or on Slack (#contributors or #taxonomy channel). And we will try take care of it.
Editor
A special editor has been developed to help us. a preview (beware your change will be lost for now) is available at https://ui.taxonomy.openfoodfacts.org/ but it's not yet really ergonomic. See also Taxonomy editor.
If you are a UX designer or developper, you can contribute to build it: http://openfoodfacts.github.io/taxonomy-editor/, or report bug and feature requests as a simple user.
GitHub
The most complicated way goes through Github. This option is only for those that are familiar with computers, downloading applications and editing large files.
Installing GitHub Desktop
- In principle it is possible to do the work on the GitHub website. Unfortunately the files related to taxonomies grew large and working on the website is not always possible. To circumvent this you need to install GitHub Desktop: Github Desktop (Linux version).
- You also need a editor to work with the large text files. Try Notepad++ on Windows or TextMate on MacOS.
- Once you have these installed, you are ready to go. By the way do not forget to create your account on Github.
Forking and branching
For those that are new to Github and collaborative editing, I'll start with some basics. First you need to make a copy of the OFF repository (all the code, taxonomies and documentation). This is called forking. You will be working on your own copy. To do this forking look for the command Clone Repository in the client. When you want make a set of changes you first need to make a copy of your local repository (called main branch). You will edit this copy. The client will ask you to name this branch. Please add your handle (Github/Slack) to that name, so we can identify you easily. And add a description to that name, such as greekTranslations, newLabels. Thus the branch name will be something like myhandle-someTranslations. Now you are setup to start editing.
Editing
Pull request
After making your changes and pushing them to your fork on Github, it is time to ask them to move them to the OFF-system. However before you do this, pull the latest official version into your branch and check for conflicts (see further).
For this you have to create a Pull Request. The command for this is in your Github-client.
In creating a pull request you have to define a title (prefix with chore:)and a description with why and what you changed.
After submitting your request the system will check the changes you made in order to make sure that they do not break things. If the suggested change does break some things, the team help you to get things resolved. Sometimes a suggested change might imply a change on the (break) testing.
Somebody from the team will have a look at your changes to make sure they are fit for purpose. A team member can make some suggestions or accept the change right away. If a suggestion implies that you have to change something: do the edit in your client, push the changes to your fork and the testing process will restart.
You might encounter the warning that there are conflicts. This happens when someone has changed the file you were working on while you were working on it. The system is then confused as it no longer knows which changes it should use. To prevent this you can pull the latest official version to your Github-client. Then you can resolve it on your side. If you are lost here (very easy), let someone from the team help you.
After you changes have been accepted and the pull request is closed by OFF, throw away the branch on your side. Try to start each new edit-session with a new branch.
Testing
After pushing (or creating a pull request) your version to Github, a series of tests will be launched. These tests will check whether your changes did not break something. If a test fails you will see the notice Some checks were not successful. For changes to taxonomies this probably happens in Pull Requests / Perl unit tests (pull_request). It is marked by a red cross.
Then you need to figure out what to do. The easiest is to leave it to the team to have a look at it. Decoding the test feedbacks is quite obscure.
If you feel up to it, have a look the details of the test. Search for fail in this document. It will show you where the error occurred. Maybe you can solve it by re-editing you files, but more probably you need to dive in the testing files. Check the instructions in Taxonomy testing out.
Taxonomy deployment
Changes to taxonomies on GitHub are not deployed instantly, they need to be built, deployed, and products need to be re-processed with the new taxonomy.
Finding new opportunities for taxonomization
- A good trick to find candidates for taxonomization is
* https://world.openfoodfacts.org/categories?filter=- * https://world.openfoodfacts.org/labels?filter=- * https://world.openfoodfacts.org/origins?filter=- * https://world.openfoodfacts.org/ingredients?filter=-
- Everything in italics is up for grabs
The future: Taxonomy editor
We have a prototype to allow editing taxonomies. Please do not using for actual taxonomy work for now. The source code and bug report/feature requests are located on GitHub. We would welcome feedback on it.