How to contribute to Barceloneta Theme on GitHub?

For example, I just submitted this issue, which would be more helpful if I could just submit a PR, but I'm extremely frustrated in trying to figure out how to go about doing this.

If someone would take the time to walk me through the tools and workfow they use to make PR for Barceloneta, I would really appreciate it. Right now, I'm comparing Barceloneta in local Plone 5.0.3.1 instance against a local, production copy of Barceloneta in Plone 5.0 where I have custom CSS (to see if I no longer need some of that custom CSS). I use Sublime Text 3, which doesn't appear to have a compatible LESS compiler, which I think I need to make a PR, otherwise I could just edit the files TTW....?

Please use the Reddit ELI5 method—and, thank you so much.

Hi @3dogMcNeill,

If you want to do a PR to fix a .css bug in Barceloneta, your PR must contain:

  • the modified .less file (in your case pagination.plone.less)
  • the updated barceloneta-compiled.css file
  • the updated barceloneta-compiled.css.map file
  • CHANGES.rst mentionning your fix

So the question is: how to generate barceloneta-compiled.css and barceloneta-compiled.css.map?

As you guessed, you need a LESS compiler.

There are 3 solutions:

SOLUTION 1: use Grunt (=the official solution)
The plonetheme.barceloneta package comes with a ready-to-use Grunt config.
So open a terminal from your plonetheme.barceloneta git checkout and do the following (you will need npm installed on your machine):

$ sudo npm install
$ sudo npm install -g grunt-cli
$ grunt less

Explanation:

  • the first command install all the needed dependencies
  • the second one install the Grunt command line tool
  • the last one compiles all the .less files and produces barceloneta-compiled.css and barceloneta-compiled.css.map

Once done, you can commit all the changes and make your PR.

SOLUTION 2: TTW, the MacGyver solution (npm install has downloaded the entire internet twice but grunt still doesn't work, and a nuclear plant is about to melt down in your neighborhood, so you are really in hurry to make your PR)

Make the change in your .less file, and then launch your Zope server, then:

  • If you have 5.0.4 (or 5.1 dev version), you can inspect the Barceloneta theme in the theming editor, open the barceloneta.plone.less file, and then click Build CSS, it will output the resulting CSS which you can copy into your sources to replace your current barceloneta-compiled.css file.
  • If you have < 5.0.4, you cannot use the Build CSS button on a file-system theme, so you first need to copy Barceloneta in your theming editor, and then you can generate the CSS.

Once done, you can commit all the changes and make your PR.
Note: you will not have an updated barceloneta-compiled.css.map file with this solution. We need to fix that in the theming editor. Nevertheless, that's not that bad, your PR will still be interesting (the .map file is only useful for debugging, so ideally it must be updated, but the nuclear plant thing sounds like a good excuse).

SOLUTION 3: use your own LESS tool
On that one, it depends on your machine, I cannot help you :slight_smile:

ABOUT MAKING A PR
I don't know how confortable you are with Github, and as you said to use the Reddit ELI5 method, let's just explain it too.

Go to your plonetheme.barceloneta git checkout, and then:

$ git checkout -b fix-something
... do the changes you want ...
$ git commit -am "Fix something"
$ git push origin fix-something

Explanation:

  • first command create a new branch named "fix-something"
  • second one commit all your changes, in your case your comment should contain "Fix #103 blabla", that way, Github will automatically closed your issue once your PR is merged
  • last one push your new branch to Github

Then go to https://github.com/plone/plonetheme.barceloneta/tree/fix-something, and click "New pull request" (and there is also a shortcut from the repo homepage).

And lastly, if you do not know how to run a Plone instance with some checked-out packages, use https://github.com/plone/buildout.coredev (the doc is here http://docs.plone.org/develop/coredev/docs/intro.html#checking-out-packages-for-fixing )

2 Likes

Also good to provide screenshots of before and after for theme changes.

1 Like

@ebrehault Awesome. Thank you! I will give this a try (the official method, not the MacGyver solution).

1 Like

For reference, Solution 1 is documented in https://github.com/plone/plonetheme.barceloneta/blob/master/HOWTO_DEVELOP.rst