Changes to Cinnamon Spices (for developer and artists)
by clem 19

Introduction

This post is for developers of Cinnamon applets, desklets and extensions, and for artists who design Cinnamon themes.

Please make sure to read this post first, to see changes explained to users: http://blog.linuxmint.com/?p=3199

We’re introducing changes in the way Cinnamon spices are being developed and maintained. All of them are beneficial to Cinnamon users and that’s the most important aspect. Some of them are also beneficial to you as developers and artists and I hope you’ll enjoy them, and some aspects might also be annoying as we’re raising expectations, defining standards and limiting your empowerment going forward.  In this post I hope to explain what’s being changed and why we implemented these changes. I hope you’ll enjoy them, if not all aspects at least some of them and I’ll be happy to answer questions you might have.

Rationale

In the past you were fully empowered and we didn’t get involved at all.

You could write anything you wanted and include any kinds of files in your ZIP archive, upload it to the Cinnamon Spices website and have users download and run what you uploaded.

It was great for some of you because there were no delays, and no intermediary between you and your users. People could comment on your spice, you would make changes and as you clicked the upload button, your new version was available to them.

The problem with that was that you were on your own…

  • If for some reason you weren’t here, no change happened (some developers haven’t been “here” for about 4 years now..). Nobody else but you could fix bugs so the only way to fix something without you was to fork your spice.
  • If for some reason you weren’t reviewing every single spice every so often to see all the changes that other developers are implementing you might have missed changes that could benefit your spice… and nobody can do that, but because you’re all developing your own spice in your own corner of the Internet, a bug fix or an improvement only affects one spice and rarely gets ported to other spices.
  • If for some reason you didn’t know how to do things, you didn’t do them properly. And it’s not really your fault. We can’t expect you to know about all the new features we implement in our API, the proper way to do something, how to support multiple instances, multiple panels, etc etc… we can’t expect everybody to keep up with the information we post (which itself isn’t sufficient to understand the core of these APIs the way we do) and so what we see a lot are spices developers which find inspiration in /usr/share/cinnamon/js files or by copying what’s being done elsewhere in other spices. And that’s great, and it works, but it’s not ideal. Ideally we’d want to be there beside you and help you change things when we see something that can be improved.
  • If for some reason you wanted to inject malicious code in a spice and upload it to hurt people, you could. And nobody did, thank God. But it’s not good enough going forward, nobody should be able to. Not only you could, but when we find out, we wouldn’t know when you did and what the exact changes were, and that’s really scary. Depending on who “you” are, maybe we can trust you, and we’ve got a way to do that, but we certainly cannot trust everyone out there. Anybody could sign up a new account and upload malicious spices, and that couldn’t go on.

Taking over

So you probably guessed it by now, we’re taking over and restricting things. That means less empowerment for developers or artists on their own spices, but it’s also a good thing because we’ll be able to assist them when it comes to packaging, bug fixes or even support for new versions of Cinnamon.

We’re placing ourselves as a delivery intermediary between the authors of spices and the Cinnamon users.

Our role will be to:

  • Review all changes to guarantee the absence of malicious code
  • Implement changes to guarantee proper packaging/installation of spices (files being in the right place for instance)
  • Implement bug fixes and accept bug fixes from other people than the author

Github

The development of all the spices now happens on Github with the following repositories:

Changes are done via pull requests against these repositories.

Changes merged onto the master branch are automatically synced towards the https://cinnamon-spices.linuxmint.com website.

The workflow is as follows:

  • You create a pull request implementing a change in your spice
  • Your pull request is merged onto the master branch
  • The Cinnamon Spices pulls the master branch, detects your commit, regenerates its copy of the spice, its ZIP archive and the global JSON index used by Cinnamon.
  • When people look for updates in System Settings, they see a new version of your spice

Authorship

Each spice comes from an author and that is something that is fundamental to us. We might be taking over and restricting your empowerment, defining standards and expecting you to follow them, it doesn’t change the fact that you’re still the author of your spice and that you have moral authority on how your spice is developed.

Nobody is going to force you to make changes in the way that spice works, and nobody will be allowed to change its behavior without your approval.

I don’t want to get too technical here just yet, I’d rather do it on Github when we formalize standards and process in .md files, but the general idea here is that you decide what your spice does and how it does it:

  • Each spice belongs to an author (which used to be in the uuid, but again I don’t want get technical here, it will be placed in a new file… the important thing is that there’s a one to one relationship between a spice and its author).
  • A pull request made by an author on his spice is ONLY reviewed for security and deployment reasons. In other words, if you pull request your own spice, the only thing that we look at is whether you’re injecting malicious code or not and whether you’re putting files in the right place.
  • A pull request made by somebody else on your spice ONLY gets accepted if it limits itself to bug fixing.
  • A pull request which modifies features or visual aspects of your spice WILL NOT be accepted without your approval.

Empowerment

Two teams were created along with the 4 github repositories, one for artists and one for developers.

As you work on spices, and even more now with us being part of their maintenance, ties and trust will develop between you and us. There are no formal distinctions or requirements when it comes to the Linux Mint team, or the Cinnamon team, we’re all developers and involved at different levels and in different projects. It’s hard to really define what the core team is and who’s part or not part of it, but the more we work together the closer you get to other developers and start being part of whatever “this” is.

At some stage, when you’re familiar with the processes, expectations and trusted by your peers, not only is there no need to review your changes anymore but you also have the ability to help us review other people changes and accept their pull requests. From a technical point of view, there comes a point where some people will be invited into these teams, so that they can get access to the master branch, commit directly and help review other people’s pull requests.

Conventions and standards

We’ll define conventions and standards as we go forward and these will be written in README.md on the github repositories. In particular we’ll define the role of uuids, authorship, team membership and standards related to pull requests.

Good luck

I hope you’ll enjoy these changes. Some of them might be hard to swallow if you read this a little too fast. You’re losing empowerment and somehow technical ownership basically and I can understand if you’re worried about this. You’re also getting us in the equation though, we’ll make spices work and install smoothly, we’ll add support for upcoming Cinnamon changes as we go forward and we’ll bring bug fixes to your spice without stepping onto its design, its features and what belongs to you.

Some of you might not be familiar with Github, artists especially and I hope this won’t be too much of a learning curve. Git is a lot of fun to use and to learn, don’t hesitate to ask questions if you’re new to this.

And then many of you are also missing and some of your spices weren’t ported over. Spices started 4 years ago, some haven’t worked in years, some were getting negative scores… We can’t guarantee that we’ll welcome all spices or that we’ll keep all spices, we want them to be popular and we want them to work. Eventually they’ll all be formatted properly, smoothly installable and they’ll get bug fixes at a much faster pace than they got in the past.

Authorship is still a key concept though, and so in the absence of consensus with an author on a particular feature, we still recommend forking and the creation of a new spice. These are still “your” spices, you just won’t be on your own maintaining them anymore.

19 thoughts on “Changes to Cinnamon Spices (for developer and artists)

  1. Reply Schorschii Jan 20,2017 20:26

    I’m new in writing desklets for cinnamon and currently finished my first battery indicator desklet. So now I would be happy to release it on Cinnamon Spices. I have to admit that I’m not that familiar with Github. So I would like to ask politely, if/when there will be a detailed guide.

  2. Reply Jason H Jan 20,2017 20:49

    This is great news for Cinnamon users, and it makes a lot of sense to accept bug fixes from anyone for extensions. Hopefully this breathes new life into some of the abandoned projects on Spices. I look at the technical ownership as more of a superficiality at best, the GPL already empowers people to do as they please with code they run – I can only see this as a win-win for users and developers.

    I can see some technical hurdles for me personally though, as I transpile the applets I maintain with Babel so I can take advantage of ES2015 features. If someone fixes a bug on the distributed, transpiled, version then it won’t be as simple as copying the change back into my repo. That’s more of a small issue specific to me, but its a common workflow on the browser side of JS that I could see become more common in this space as the version of Spidermonkey in CJS doesn’t have full ES2015 support.

    With that said, hopefully it won’t be too resource intensive on the Mint team to vet every applet PR, but it sounds like you guys know how you’re allocating resources.

    Great work on the site, it looks really clean and modern. Looking forward to what this brings.

  3. Reply Sam Riggs Jan 21,2017 02:01

    Smart move Clem glad to see it happen :)

  4. Reply ccprog Jan 24,2017 21:09

    I found that if you download a .zip from the new website and install it, it will immediately be shown as updatable in cinnamon-settings/applets. It looks like there is some rewriting going on for metadata.json on a direct installation that does not happen for the download packages.

    • Reply clem Jan 25,2017 18:52

      Ah.. we might have to update “last-edited”, within the metadata.json file, while generating the ZIP archive.. can you create an issue for this so we can keep track of it?

  5. Reply Rizwan Jan 25,2017 11:25

    Hi Clem, I want to build applets. I am good with python but new with js. Is there anyway I can build applet with python???

  6. Reply pdcurtis Jan 26,2017 19:32

    Clem,
    I have only just found this and my first thoughts are that it will get round a lot of the problems in the long term, in particular old unmaintained applets which still have high rankings.

    At present I see one problem and that is that i had a lot of information including requirements for other software to be loaded to allow my applets to work and that all seems to have disappeared. This will be a common problem with many of the ‘monitoring’ applets as they are currently implemented.
    The only mechanism short term is by a comment from the author so I do not think it advisable to reset comments, perhaps go back a year if you want to tidy up.
    I can not see anywhere a way to specify the range of Cinnamon Versions which the applet is designed and tested for and that is required as long as some users are running Mint 17.x/Cinnamon 2.x (or even earlier).
    Is there a way you can add a list of dependencies or check and warn users.
    Sorry if this sounds a bit negative but it is all sudden to me and I am away for a period so I not do much short term and I have not had time to do the home work I should and I may have missed something.

    • Reply clem Jan 26,2017 22:34

      Hi,

      It’s ok. It’s a very legitimate worry. One thing we added was support for README files.

      Add a README.md at the root level of your spice and you can use that file to insert instructions and details. Write the content in Markdown format (i.e. the same format used on Github for instance).

      The content of the README.md will be shown to Github visitors of course, but it will also be parsed and rendered in HTML within the your spice page on the Cinnamon Spices website.

      • Reply pdcurtis Jan 27,2017 09:42

        Clem,
        Why not automatically transfer the text from the original web site to the README.md file as a start for the applets. I, for one, do not have the last version with me for any of my 5 applets as the final edits were on-line. If that is not possible perhaps you can send them to the applet writers or make the original site available again to the registered users for a period. I hate reinventing wheels!

        • Reply clem Jan 27,2017 16:59

          Yes, we can run a script to do that. In the meantime you can access the old description with a time machine or wayback website, or search engine cache.

      • Reply pdcurtis Jan 28,2017 19:54

        Clem,
        Thanks for the wayback website and cache suggestions. My experience, which may be useful to others, was that the Yahoo cache was old enough to be useful but Google too up-to-date. Waybach was not recent enough.

        Is there a definition of the criteria anywhere for ‘dangerous’. What applet writers need to do to remove it and how will you handle it in the future?

        Currently I have my applets on Github at https://github.com/pdcurtis/cinnamon-applets, Can I request changes to be pulled directly or do I need to Clone https://github.com/linuxmint/cinnamon-spices-applets and potentially lose my existing audit trail?

        • Reply clem Feb 6,2017 12:04

          Hi,

          Sorry about the moderation on this comment (it took a little while to show up). We can’t pull directly from 3rd party sources for security and maintenance reasons. In regards to “dangerous”, are you talking about the little warning that shows up in the System Settings? If so it’s related to particular use of libraries within the applets… synchronous ones for instance.

  7. Reply mike Feb 9,2017 10:09

    Clem, I am getting a security certificate warning from my rss feed when it tries to access segfault.

  8. Reply mrman Feb 11,2017 00:46

    Great. This is really important, there are too many people wanting to see things fail, be it Mint or just Linux in general. I agree with this decision, mint-team should be keeping control on ANY aspect or areas that could force something on the innocent user without their knowledge or yours.

    good job.

Leave a Reply