Clarifying the "note these steps"
[mediagoblin.git] / docs / source / siteadmin / relnotes.rst
1 .. MediaGoblin Documentation
2
3 Written in 2012 by MediaGoblin contributors
4
5 To the extent possible under law, the author(s) have dedicated all
6 copyright and related and neighboring rights to this software to
7 the public domain worldwide. This software is distributed without
8 any warranty.
9
10 You should have received a copy of the CC0 Public Domain
11 Dedication along with this software. If not, see
12 <http://creativecommons.org/publicdomain/zero/1.0/>.
13
14 .. _release-notes:
15
16 =============
17 Release Notes
18 =============
19
20 This chapter has important information for releases in it.
21 If you're upgrading from a previous release, please read it
22 carefully, or at least skim over it.
23
24 .. note::
25
26 ALWAYS do backups before upgrading, especially before
27 running migrations! That way if something goes wrong, we can fix
28 things!
29
30 And be sure to shut down your current mediagoblin/celery processes
31 before upgrading!
32
33 .. note::
34
35 The MediaGoblin repository used to be on gitorious.org, but since
36 gitorious.org shut down, we had to move. We are presently on
37 Savannah. You may need to update your git repository location::
38
39 git remote set-url origin git://git.savannah.gnu.org/mediagoblin.git
40
41
42 0.8.0
43 =====
44
45 This release has a number of changes related to the way we recommend
46 building MediaGoblin; upgrade steps are below, but if you run into
47 trouble, consider pinging the MediaGoblin list or IRC channel.
48
49 **Do this to upgrade**
50
51 0. If you haven't already, switch the git remote URL:
52 ``git remote set-url origin git://git.savannah.gnu.org/mediagoblin.git``
53 1. Update to the latest release. If checked out from git, run:
54 ``git fetch && git checkout -q v0.8.0``
55 2. Run
56 ``./bootstrap.sh && ./configure && make``
57 3. Also run
58 ``./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate``
59
60 Please note the important steps of 0 and 2, which have not appeared in
61 prior upgrade guides!
62
63 Additionally:
64
65 - Are you using audio or video media types? In that case, you'll need
66 to update your Gstreamer instance to 1.0.
67 - The Pump API needs some data passed through to the WSGI application,
68 so if you are using apache with mod_wsgi you should be sure to make
69 sure to add "WSGIPassAuthorization On" to your config. (Using the
70 default MediaGoblin documnetation and config, things should work
71 as-is.)
72
73
74 **Bugfixes/improvements:**
75
76 - Preliminary / experimental support for Python 3!
77 - Footer forced to the bottom of page
78 - Massive improvements to Pump API support
79 - Able to run on multiple existing Pump clients! Including Pumpa
80 and Dianara!
81 - much cleaner ./configure && make support; it's now the default
82 - Clearer documentation on permissions and installation
83 - Switched from Transifex, which had become proprietary, to an
84 instance of Pootle hosted for GNU
85 - Moved to Gstreamer 1.0! This also adds a new thumbnailer which
86 gives much better results in
87 - Removed terrible check-javascript-dependencies-into-your-application
88 setup, now using Bower for dependency tracking
89 - Put some scaffolding in place for Alembic, which will be used for
90 future mitration work
91 - Automatically create a fresh mediagoblin.ini from
92 mediagoblin.ini.example
93 - no more need for mediagoblin_local.ini (though it's still supported)
94 - Fix lowercasing of username in auth steps
95 - Slowly moving towards removing global state (a source of many bugs)
96
97 0.7.1
98 =====
99
100 This is a purely bugfix release. Important changes happened since
101 0.7.0; if running MediaGoblin 0.7.0, an upgrade is highly recommended;
102 see below. This release is especially useful if you have been running
103 postgres and have been receiving seemingly random database transaction
104 errors.
105
106 **Do this to upgrade**
107
108 1. Update to the latest release. If checked out from git, run:
109 ``git fetch && git checkout -q v0.7.1 && git submodule init && git submodule update``
110 2. Make sure to run
111 ``./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate``
112
113 That's it, probably! If you run into problems, don't hesitate to
114 `contact us <http://mediagoblin.org/pages/join.html>`_
115 (IRC is often best).
116
117 **Bugfixes/improvements:**
118
119 - The *MOST IMPORTANT* change in this release:
120 Disabling a couple of non-critical features that were causing
121 database transaction issues. (These should be back by 0.8.0.)
122
123 + Disabled the "checking if the database is up to date at
124 mediagoblin startup" feature
125 + Disabled the garbage collection stuff by default for now
126 (You can set garbage_collection under the config mediagoblin
127 header to something other than 0 to turn it back on for now, but
128 it's potentially risky for the moment.)
129
130 - Some fixes to the 0.7.0 docs
131 - Fixed Sandy 70s speedboat navbar by updating git submodule
132 - Added support for cr2 files in raw_image media type
133 - Added a description to setup.py
134 - Collection and CollectionItem objects now have nicer in-python representations
135 - Fixed unicode error with raw image mediatype logging
136 - Fixed #945 "Host metadata does not confirm to spec (/.well-known/meta-data)"
137
138 + Add XRD+XML formatting for /.well-known/host-meta
139 + Add /.well-known/webfinger API to lookup user hrefs
140
141 - deleteuser gmg subcommand now fails gracefully
142 - Removed a false download link from setup.py
143
144 0.7.0
145 =====
146
147 **Do this to upgrade**
148
149 1. Update to the latest release. If checked out from git, run:
150 ``git fetch && git checkout -q v0.7.0 && git submodule init && git submodule update``
151 2. Make sure to run
152 ``./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate``
153
154 (NOTE: earlier versions of the 0.7.0 release instructions left out the
155 ``git submodule init`` step! If you did an upgrade earlier based on
156 these instructions and your theme looks weirdly aligned, try running
157 the following:)
158
159 ``git submodule init && git submodule update``
160
161 That's it, probably! If you run into problems, don't hesitate to
162 `contact us <http://mediagoblin.org/pages/join.html>`_
163 (IRC is often best).
164
165 **New features:**
166
167 - New mobile upload API making use of the
168 `Pump API <https://github.com/e14n/pump.io/blob/master/API.md>`_
169 (which will be the foundation for MediaGoblin's federation)
170 - New theme: Sandy 70s Speedboat!
171
172 - Metadata features! We also now have a json-ld context.
173
174 - Many improvements for archival institutions, including metadata
175 support and featuring items on the homepage. With the (new!)
176 archivalook plugin enabled, featuring media is possible.
177 Additionally, metadata about the particular media item will show up
178 in the sidebar.
179
180 In the future these plugins may be separated, but for now they have
181 come together as part of the same plugin.
182
183 - There is a new gmg subcommand called batchaddmedia that allows for
184 uploading many files at once. This is aimed to be useful for
185 archival institutions and groups where there is an already existing
186 and large set of available media that needs to be included.
187 - Speaking of, the call to postgres in the makefile is fixed.
188 - We have a new, generic media-page context hook that allows for
189 adding context depending on the type of media.
190 - Tired of video thumbnails breaking during processing all the time?
191 Good news, everyone! Video thumbnail generation should not fail
192 frequently anymore. (We think...)
193 - You can now set default permissions for new users in the config.
194
195 - bootstrap.sh / gnu configuration stuff still exists, but moves to be
196 experimental-bootstrap.sh so as to not confuse newcomers. There are
197 some problems currently with the autoconf stuff that we need to work
198 out... we still have interest in supporting it, though help is
199 welcome.
200
201 - MediaGoblin now checks whether or not the database is up to date
202 when starting.
203 - Switched to `Skeleton <http://www.getskeleton.com/>`_ as a system for
204 graphic design.
205 - New gmg subcommands for administrators:
206 - A "deletemedia" command
207 - A "deleteuser" command
208 - We now have a blogging media type... it's very experimental,
209 however. Use with caution!
210 - We have switched to exifread as an external library for reading EXIF
211 data. It's basically the same thing as before, but packaged
212 separately from MediaGoblin.
213 - Many improvements to internationalization. Also (still rudimentary,
214 but existant!) RTL language support!
215
216 **Known issues:**
217 - The host-meta is now json by default; in the spec it should be xml by
218 default. We have done this because of compatibility with the pump
219 API. We are checking with upstream to see if there is a way to
220 resolve this discrepancy.
221
222
223 0.6.1
224 =====
225
226 This is a short, bugfix release.
227
228 **Do this to upgrade**
229
230 1. Update to the latest release. If checked out from git, run:
231 ``git fetch && git checkout -q v0.6.1``
232 2. Make sure to run
233 ``./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate``
234
235 This release switches the default terms of service to be off by
236 default and corrects some mistakes in the default terms of service.
237
238 Turning the terms of service on is very easy, just set ``show_tos`` in
239 the ``[mediagoblin]`` section of your config to ``true``.
240
241
242 0.6.0
243 =====
244
245 **Do this to upgrade**
246
247 1. Update to the latest release. If checked out from git, run:
248 ``git fetch && git checkout -q v0.6.0``
249 2. Make sure to run
250 ``./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate``
251
252 That's it, probably! If you run into problems, don't hesitate to
253 `contact us <http://mediagoblin.org/pages/join.html>`_
254 (IRC is often best).
255
256 This tool has a lot of new tools for administrators, hence the
257 nickname "Lore of the Admin"!
258
259 **New features:**
260
261 - New tools to control how much users can upload, both as a general
262 user limit, or per file.
263
264 You can set this with the following options in your mediagoblin
265 config file: `upload_limit` and `max_file_size`. Both are integers
266 in megabytes.
267
268 There is an option to control how much each individual user can
269 upload too, though an interface for this is not yet exposed. See
270 the "uploaded" field on the core__users table.
271
272 - MediaGoblin now contains an authentication plugin for ldap! You
273 can turn on the mediagoblin.plugins.ldap plugin to make use of
274 this. See the documentation: :ref:`ldap-plugin`
275
276 - There's a new command line upload tool! At long last! See
277 `./bin/gmg addmedia --help` for info on how to use this.
278
279 - There's now a terms of service document included in MediaGoblin.
280 It's turned on by default, but you can turn it off if you prefer,
281 just set the configuration option of `show_tos` in the [mediagoblin]
282 section of your config to false.
283
284 Alternately, you can override the template for the terms of service
285 document to set up your own.
286
287 - We have a lot of new administrative tooling features!
288 - There's a built-in privileges/permissions system now.
289 Administrators are given access to modifying these parameters
290 from a user administration panel.
291 - Users can submit reports about other problematic users or media
292 and administrators are given tools to resolve said reports and
293 ban/unban users if needed.
294
295 - New version of video.js is included with MediaGoblin. Slight
296 amount of skinning to match the MediaGoblin look, otherwise also
297 uses the new default skin.
298
299 Developer-oriented changes:
300
301 - New developer tool for quickly setting up a development environment
302 in `devtools/make_example_database.sh`. Requires doing a checkout
303 of our other tool `mg_dev_environments <https://gitorious.org/mediagoblin/mg-dev-environments/>`_
304 (probably in the parent Directory) though!
305 - A "foundations" framework has entered into the codebase.
306 This is mostly just relevant to coders, but it does mean that it's
307 much easier to add database structures that need some entries filled
308 automatically by default.
309 - Refactoring to the authentication code and the reprocessing code
310
311
312 0.5.1
313 =====
314
315 v0.5.1 is a bugfix release... the steps are the same as for 0.5.1.
316
317 **Bugfixes:**
318
319 - python 2.6 compatibility restored
320 - Fixed last release's release notes ;)
321
322
323 0.5.0
324 =====
325
326 **NOTE:** If using the API is important to you, we're in a state of
327 ransition towards a new API via the Pump API. As such, though the old
328 API still probably works, some changes have happened to the way oauth
329 works to make it more Pump-compatible. If you're heavily using
330 clients using the old API, you may wish to hold off on upgrading for
331 now. Otherwise, jump in and have fun! :)
332
333 **Do this to upgrade**
334
335 1. Make sure to run
336 ``./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate``
337 after upgrading.
338
339 .. mention something about new, experimental configure && make support
340
341 2. Note that a couple of things have changed with ``mediagoblin.ini``. First
342 we have a new Authentication System. You need to add
343 ``[[mediagoblin.plugins.basic_auth]]`` under the ``[plugins]`` section of
344 your config file. Second, media types are now plugins, so you need to add
345 each media type under the ``[plugins]`` section of your config file.
346
347
348 3. We have made a script to transition your ``mediagoblin_local.ini`` file for
349 you. This script can be found at:
350
351 http://mediagoblin.org/download/0.5.0_config_converter.py
352
353 If you run into problems, don't hesitate to
354 `contact us <http://mediagoblin.org/pages/join.html>`_
355 (IRC is often best).
356
357 **New features**
358
359 * As mentioned above, we now have a plugable Authentication system. You can
360 use any combination of the multiple authentication systems
361 (:ref:`basic_auth-chapter`, :ref:`persona-chapter`, :ref:`openid-chapter`)
362 or write your own!
363 * Media types are now plugins! This means that new media types will
364 be able to do new, fancy things they couldn't in the future.
365 * We now have notification support! This allows you to subscribe to media
366 comments and to be notified when someone comments on your media.
367 * New reprocessing framework! You can now reprocess failed uploads, and
368 send already processed media back to processing to re-transcode or resize
369 media.
370 * Comment preview!
371 * Users now have the ability to change their email associated with their
372 account.
373 * New oauth code as we move closer to federation support.
374 * Experimental pyconfigure support for GNU-style configue and makefile
375 deployment.
376 * Database foundations! You can now pre-populate the database models.
377 * Way faster unit test run-time via in-memory database.
378 * All mongokit stuff has been cleaned up.
379 * Fixes for non-ascii filenames.
380 * The option to stay logged in.
381 * Mediagoblin has been upgraded to use the latest `celery <http://celeryproject.org/>`_
382 version.
383 * You can now add jinja2 extensions to your config file to use in custom
384 templates.
385 * Fixed video permission issues.
386 * Mediagoblin docs are now hosted with multiple versions.
387 * We removed redundent tooltips from the STL media display.
388 * We are now using itsdangerous for verification tokens.
389
390
391 0.4.1
392 =====
393
394 This is a bugfix release for 0.4.0. This only implements one major
395 fix in the newly released document support which prevented the
396 "conversion via libreoffice" feature.
397
398 If you were running 0.4.0 you can upgrade to v0.4.1 via a simple
399 switch and restarting mediagoblin/celery with no other actions.
400
401 Otherwise, follow 0.4.0 instructions.
402
403
404 0.4.0
405 =====
406
407 **Do this to upgrade**
408
409 1. Make sure to run
410 ``./bin/python setup.py develop --upgrade && ./bin/gmg dbupdate``
411 after upgrading.
412 2. See "For Theme authors" if you have a custom theme.
413 3. Note that ``./bin/gmg theme assetlink`` is now just
414 ``./bin/gmg assetlink`` and covers both plugins and assets.
415 Keep on reading to hear more about new plugin features.
416 4. If you want to take advantage of new plugins that have statically
417 served assets, you are going to need to add the new "plugin_static"
418 section to your nginx config. Basically the following for nginx::
419
420 # Plugin static files (usually symlinked in)
421 location /plugin_static/ {
422 alias /srv/mediagoblin.example.org/mediagoblin/user_dev/plugin_static/;
423 }
424
425 Similarly, if you've got a modified paste config, you may want to
426 borrow the app:plugin_static section from the default paste.ini
427 file.
428 5. We now use itsdangerous for sessions; if you had any references to
429 beaker in your paste config you can remove them. Again, see the
430 default paste.ini config
431 6. We also now use git submodules. Please do:
432 ``git submodule init && git submodule update``
433 You will need to do this to use the new PDF support.
434
435 **For theme authors**
436
437 If you have your own theme or you have any "user modified templates",
438 please note the following:
439
440 * mediagoblin/bits/ files above-content.html, body-end.html,
441 body-start.html now are renamed... they have underscores instead of
442 dashes in the filenames now :)
443 * There's a new file: ``mediagoblin/bits/frontpage_welcome.html``.
444 You can easily customize this to give a welcome page appropriate to
445 your site.
446
447
448 **New features**
449
450 * PDF media type!
451 * Improved plugin system. More flexible, better documented, with a
452 new plugin authoring section of the docs.
453 * itsdangerous based sessions. No more beaker!
454 * New, experimental Piwigo-based API. This means you should be able
455 to use MediaGoblin with something like Shotwell. (Again, a word of
456 caution: this is *very experimental*!)
457 * Human readable timestamps, and the option to display the original
458 date of an image when available (available as the
459 "original_date_visible" variable)
460 * Moved unit testing system from nosetests to py.test so we can better
461 handle issues with sqlalchemy exploding with different database
462 configurations. Long story :)
463 * You can now disable the ability to post comments.
464 * Tags now can be up to length 255 characters by default.
465
466
467 0.3.3
468 =====
469
470 **Do this to upgrade**
471
472 1. Make sure to run ``bin/gmg dbupdate`` after upgrading.
473 2. OpenStreetMap is now a plugin, so if you want to use it, add the
474 following to your config file:
475
476 .. code-block:: ini
477
478 [plugins]
479 [[mediagoblin.plugins.geolocation]]
480
481 If you have your own theme, you may need to make some adjustments to
482 it as some theme related things may have changed in this release. If
483 you run into problems, don't hesitate to
484 `contact us <http://mediagoblin.org/pages/join.html>`_
485 (IRC is often best).
486
487 **New features**
488
489 * New dropdown menu for accessing various features.
490
491 * Significantly improved URL generation. Now mediagoblin won't give
492 up on making a slug if it looks like there will be a duplicate;
493 it'll try extra hard to generate a meaningful one instead.
494
495 Similarly, linking to an id no longer can possibly conflict with
496 linking to a slug; /u/username/m/id:35/ is the kind of reference we
497 now use to linking to entries with ids. However, old links with
498 entries that linked to ids should work just fine with our migration.
499 The only urls that might break in this release are ones using colons
500 or equal signs.
501
502 * New template hooks for plugin authoring.
503
504 * As a demonstration of new template hooks for plugin authoring,
505 openstreetmap support now moved to a plugin!
506
507 * Method to add media to collections switched from icon of paperclip
508 to button with "add to collection" text.
509
510 * Bug where videos often failed to produce a proper thumbnail fixed!
511
512 * Copying around files in MediaGoblin now much more efficient, doesn't
513 waste gobs of memory.
514
515 * Video transcoding now optional for videos that meet certain
516 criteria. By default, MediaGoblin will not transcode webm videos
517 that are smaller in resolution than the MediaGoblin defaults, and
518 MediaGoblin can also be configured to allow theora files to not be
519 transcoded as well.
520
521 * Per-user license preference option; always want your uploads to be
522 BY-SA and tired of changing that field? You can now set your
523 license preference in your user settings.
524
525 * Video player now responsive; better for mobile!
526
527 * You can now delete your account from the user preferences page if
528 you so wish.
529
530 **Other changes**
531
532 * Plugin writers: Internal restructuring led to mediagoblin.db.sql* be
533 mediagoblin.db.* starting from 0.3.3
534
535 * Dependency list has been reduced not requiring the "webob" package anymore.
536
537 * And many small fixes/improvements, too numerous to list!
538
539
540 0.3.2
541 =====
542
543 This will be the last release that is capable of converting from an earlier
544 MongoDB-based MediaGoblin instance to the newer SQL-based system.
545
546 **Do this to upgrade**
547
548 # directory of your mediagoblin install
549 cd /srv/mediagoblin.example.org
550
551 # copy source for this release
552 git fetch
553 git checkout tags/v0.3.2
554
555 # perform any needed database updates
556 bin/gmg dbupdate
557
558 # restart your servers however you do that, e.g.,
559 sudo service mediagoblin-paster restart
560 sudo service mediagoblin-celeryd restart
561
562
563 **New features**
564
565 * **3d model support!**
566
567 You can now upload STL and OBJ files and display them in
568 MediaGoblin. Requires a recent-ish Blender; for details see:
569 :ref:`deploying-chapter`
570
571 * **trim_whitespace**
572
573 We bundle the optional plugin trim_whitespace which reduces the size
574 of the delivered html output by reducing redundant whitespace.
575
576 See :ref:`core-plugin-section` for plugin documentation
577
578 * **A new API!**
579
580 It isn't well documented yet but we do have an API. There is an
581 `android application in progress <https://gitorious.org/mediagoblin/mediagoblin-android>`_
582 which makes use of it, and there are some demo applications between
583 `automgtic <https://github.com/jwandborg/automgtic>`_, an
584 automatic media uploader for your desktop
585 and `OMGMG <https://github.com/jwandborg/omgmg>`_, an example of
586 a web application hooking up to the API.
587
588 This is a plugin, so you have to enable it in your mediagoblin
589 config file by adding a section under [plugins] like::
590
591 [plugins]
592 [[mediagoblin.plugins.api]]
593
594 Note that the API works but is not nailed down... the way it is
595 called may change in future releases.
596
597 * **OAuth login support**
598
599 For applications that use OAuth to connect to the API.
600
601 This is a plugin, so you have to enable it in your mediagoblin
602 config file by adding a section under [plugins] like::
603
604 [plugins]
605 [[mediagoblin.plugins.oauth]]
606
607 * **Collections**
608
609 We now have user-curated collections support. These are arbitrary
610 galleries that are customizable by users. You can add media to
611 these by clicking on the paperclip icon when logged in and looking
612 at a media entry.
613
614 * **OpenStreetMap licensing display improvements**
615
616 More accurate display of OSM licensing, and less disruptive: you
617 click to "expand" the display of said licensing.
618
619 Geolocation is also now on by default.
620
621 * **Miscelaneous visual improvements**
622
623 We've made a number of small visual improvements including newer and
624 nicer looking thumbnails and improved checkbox placement.
625
626
627
628 0.3.1
629 =====
630
631 **Do this to upgrade**
632
633 1. Make sure to run ``bin/gmg dbuptdate`` after upgrading.
634
635 2. If you set up your server config with an older version of
636 mediagoblin and the mediagoblin docs, it's possible you don't
637 have the "theme static files" alias, so double check to make
638 sure that section is there if you are having problems.
639
640
641
642 **New features**
643
644 * **theming support**
645
646 MediaGoblin now also includes theming support, which you can
647 read about in the section :ref:`theming-chapter`.
648
649 * **flatpages**
650
651 MediaGoblin has a flatpages plugin allowing you to add pages that
652 are aren't media-related like "About this site...", "Terms of
653 service...", etc.
654
655 See :ref:`core-plugin-section` for plugin documentation
656
657
658 0.3.0
659 =====
660
661 This release has one important change. You need to act when
662 upgrading from a previous version!
663
664 This release changes the database system from MongoDB to
665 SQL(alchemy). If you want to setup a fresh instance, just
666 follow the instructions in the deployment chapter. If on
667 the other hand you want to continue to use one instance,
668 read on.
669
670 To convert your data from MongoDB to SQL(alchemy), you need
671 to follow these steps:
672
673 1. Make sure your MongoDB is still running and has your
674 data, it's needed for the conversion.
675
676 2. Configure the ``sql_engine`` URI in the config to represent
677 your target database (see: :ref:`deploying-chapter`)
678
679 3. You need an empty database.
680
681 4. Then run the following command::
682
683 bin/gmg [-cf mediagoblin_config.ini] convert_mongo_to_sql
684
685 5. Start your server and investigate.
686
687 6. That's it.