S3's ObjectMetadata#[]= should have a note about non-copied metadata attributes

[schmich]

We were bitten pretty badly by the issue mentioned in #180, and it took us some time to figure out what was happening.

Our code was very roughly this:

# create.rb
obj = s3.buckets[bucket].objects[key]
obj.write(contents, :server_side_encryption => :aes256)

# update.rb
obj = s3.buckets[bucket].objects[key]
obj.metadata['name'] = value

I will grant that AWS veterans will know that updating an object's metadata uses CopyObject under the covers, but new users coding diligently from the docs will most likely miss this subtle point.

A few ideas for helping users avoid this pitfall:

1. At a minimum, add some documentation to ObjectMetadata#[]=(name, value) to mention the caveat of not preserving certain attributes (:server_side_encryption, :reduced_redundancy, ...). You could even copy the note from S3Object#copy_from.
2. Mention that if these attributes need to be preserved, that the user should set them on the object or use S3Object#copy_from manually.
3. Add a method on S3Object or ObjectMetadata to do an attribute-preserving metadata update. This is a bit more invasive and, as #180 mentioned, hints at a leaky abstraction.

I'm happy to make the doc changes myself and submit a pull request if help is needed.

Regards, Chris

[awood45]

Sorry for the delay - I'm picking this up now.

[awood45]

I'm submitting a change that updates the documentation and marks ObjectMetadata#[]= as deprecated. The added documentation should make the risks of the []= function especially clear.

[schmich]

Perfect, thanks a bunch, Alex. The usage is much clearer with your updates.