Could we merge Patterns-site and Patterns again?

[jcbrand]

Hi @pilz and @cornae

As far as I know, Patterns-site was forked out of Patterns to keep Patterns small, right?
Are there any other reasons why Patterns-site was created?

Currently a new clone of Patterns-site is 69MB

jc@ploneintra-13:33:~/tmp$ du -hs Patterns-site/
69M     Patterns-site
jc@ploneintra-13:43:~/tmp/Patterns-site (gh-pages)$ du -hs .git
43M     .git

and a new clone of Patterns is 66MB

jc@ploneintra-13:36:~/tmp (container)$ du -hs Patterns
66M     Patterns
jc@ploneintra-13:43:~/tmp/Patterns (master)$ du -hs .git
47M     .git

Without the .git folders Patterns is 19MB and Patterns-site 27MB.

So there's actually not much of a size benefit at all when one ignores the git histories, and instead we get much duplication and confusion.

For example:

• There are now demo folders in both repos and we have to take care to keep them synchronized.
• Patterns has the old version of the site and Patternslib-site has a new version

I'm currently working on pat-clone and I'm not sure where I should put the demo files. I previously added pat-masonry's demo files in Patterns, but now I think @cornae is not even aware of that because he works in Patterns-site.

To avoid these problems I therefore propose that we merge the two repos again.

We can purge the old unused Binary files from git and thereby make the .git folders much smaller.

This will solve the size problem.

For archaeological purposes we can fork the current Patterns repo (call it Patterns-archive or something) so that we still have a copy of the old git history with all the old Binary files.

What do you say?

[pilz]

big question, requires discussion. I propose to do that next week.

On 6 Mar 2015, at 13:52, JC Brand notifications@github.com wrote:

Hi @pilz https://github.com/pilz and @cornae https://github.com/cornae
As far as I know, Patterns-site was forked out of Patterns to keep Patterns small, right?
Are there any other reasons why Patterns-site was created?

Currently a new clone of Patterns-site is 69MB

jc@ploneintra-13:33:/tmp$ du -hs Patterns-site/
69M Patterns-site
jc@ploneintra-13:43:/tmp/Patterns-site (gh-pages)$ du -hs .git
43M .git
and a new clone of Patterns is 66MB

jc@ploneintra-13:36:/tmp (container)$ du -hs Patterns
66M Patterns
jc@ploneintra-13:43:/tmp/Patterns (master)$ du -hs .git
47M .git
Without the .git folders Patterns is 19MB and Patterns-site 27MB.

So there's actually not much of a size benefit at all when one ignores the git histories, and instead we get much duplication and confusion.

For example:

There are now demo folders in both repos and we have to take care to keep them synchronized.
Patterns has the old version of the site and Patternslib-site has a new version
I'm currently working on pat-clone and I'm not sure where I should put the demo files. I previously added pat-masonry's demo files in Patterns, but now I think @cornae https://github.com/cornae is not even aware of that because he works in Patterns-site.

To avoid these problems I therefore propose that we merge the two repos again.

We can purge the old unused Binary files http://git-scm.com/book/en/v2/Git-Internals-Maintenance-and-Data-Recovery#Removing-Objects from git and thereby make the .git folders much smaller.

This will solve the size problem.

For archaeological purposes we can fork the current Patterns repo (call it Patterns-archive or something) so that we still have a copy of the old git history with all the old Binary files.

What do you say?

—
Reply to this email directly or view it on GitHub #4.

Alexander Pilz
SYSLAB.COM GmbH, Landwehrstrasse 60-62, 80336 Munich, Germany
Tel: +49 89 3063589-0 - Fax: +49 89 3063589-9
http://www.syslab.com - Amtsgericht Muenchen, HRB 135057
Steuernummer 143/184/50154 - Ust.-ID: DE212842815

[jcbrand]

@wichert: According to @cornae you have some reasons for why it's a good idea to have Patterns-site separate from Patterns. Could you please mention them here or point me to a place where I can read them?

[wichert]

We had several reasons for the split initially:

• during development you want to use a modular setup in demos to ease with debugging. For the website you really want to use a bundle. A special command to do a search-and-replace on all files was added to facilitate that, but that led to unnecessary conflicts and accidental bad commits.
• having all website content in the root of the source package made for a messy directory structure.
• we used the public website to test changes as well, which made it always out of sync with the current release and/or offer a development snapshot instead of a proper release as download.

The split helped to address these issues, but introduced some new ones. I still see some value in having the main website separate from the code, but I'm not entirely sure how strongly opinionated I am about that. Considering that others are doing the majority of the work now I certainly don't want to block a merge if the current developers feel that is the best approach.

[jcbrand]

Thanks @wichert for the feedback. Good to know the original motivations.

I find the current situation untenable due to the duplication of documentation and extra work required to keep the two repos in sync.

during development you want to use a modular setup in demos to ease with debugging. For the website you really want to use a bundle. A special command to do a search-and-replace on all files was added to facilitate that, but that led to unnecessary conflicts and accidental bad commits.

We should be able to come up with a way to use require.js for dev and a bundle file for production.
Either via the URL query string or having a dev.html page or something else.

having all website content in the root of the source package made for a messy directory structure.

True but a price worth paying I think. We can ignore all the Jekyll stuff in bower.json so that at least the bower package is much cleaner.

we used the public website to test changes as well, which made it always out of sync with the current release and/or offer a development snapshot instead of a proper release as download.

The public website also acts as the documentation store, so frequent updates to it as patterns are changed or introduced are to be expected. I think the important thing is to manage releases properly.

The current/live release should always have a release tag in git (and on Github).
Experimental changes and tests of new markup should go into feature branches and only merged when acceptable.

[pilz]

Current Problems with the separation of website and code

• There is no easy way to write documentation to go on the website
• We must have documentation in patternslib so that we can show how it works, test against it and develop on it.
• We have two documentations, one in patternslib and one in website. The former to demo a pattern and the latter to store the full documentation, both partly overlapping. It is hard to keep them in sync and they overlap.
• There is no way to easily show documentation of external (to core) patterns in the website as well.

However, we don't necessarily need to merge the repositories to fix that.

Proposed Solution

• All pattern demo (documentation.md) goes back into patternslib.
  This will allow developers and designers to work on patterns again. The documentation will work standalone and include all minimal necessary html, css and js to run and demo a pattern.
• The demo folder in the current patterns website goes away completely.
• The patterns website will use bower to fetch patternslib (and later potentially other external patterns) and link it into the website (_site/bower_components/etc). That will make the patterns available from within the website for referencing.
• The patterns website will continue to contain all general documentation like introduction, designer/integrator/pattern developer/core developer documentation.
• The patterns website will automatically fetch each pattern's documentation from the linked in bower_components pattern repo and show it using pat-markdown.
  It will also fetch a pattern's functional sass/css and include it into the website sass/css include file. There is a naming convention for the css/sass file as well (e.g. name-of-pattern.[css|sass]).
• Every documentation page has a link to the corresponding github page to edit it quickly. Editing on github will result in a pull request which make the change immediately available on the website once we merge and release it.

Deliverables

• Manually consolidate all individual patterns documentation and make it live in patternslib.
  (All)
• Complete missing documentation.
  (All with help from Cornelis and JC)
• Create and update all general documentation and make it live in patterns website (introduction, designer/integrator/pattern developer/core developer).
  (Cornelis, JC, Alex)
• Create a mechanism that pulls patternslib from bower into website and makes documetation.md and sass/css available there.
  (JC)
• Update all individual patterns to have an up to date documentation.md, a sass/css file and a index.html that uses pat-markdown to include it.
  (All)
• Create a simple base.css for patternslib which is included by index.html to provide a decent development and testing experience.
  (Cornelis)
• Provide "Edit this documentation" link functionality
  (JC/Alex)
• Update the yeoman new pattern creator to generate the correct documentation structure.
  (JC)
• Remove demo folder from the website
  (final cleanup, All)

Further Reading

Based on that work, we can then complete the website by doing:

• Design a documentation section
  (Cornelis)
• Port the download tool
  (Alex)
• Add rich examples
  (The patterns website is actually one then)

[cornae]

This item might become current again since the design update I did today to patternslib.com

I temporarily added the demos in a quick and dirty way to the site to make them run (some or broken still like calendar).

I also copied the documentation over to the Jekyll site — at least for the moment — so that I can view and maintain it there.