[GitHub] ctubbsii commented on a change in pull request #1: Provide initial README
ctubbsii commented on a change in pull request #1: Provide initial README URL: https://github.com/apache/fluo-bytes/pull/1#discussion_r132545078 ## File path: README.md ## @@ -0,0 +1,102 @@ + + +# Apache Fluo Bytes + +[![Build Status][ti]][tl] [![Apache License][li]][ll] [![Maven Central][mi]][ml] [![Javadoc][ji]][jl] + +**Apache Fluo Bytes is a simple library with the goal of providing an extremely +stable API for handling bytes, suitable for use in [Apache Fluo][fluo] and +other projects' APIs.** + +## Features and Goals + +This project aims to fill a void in Java, by providing convenient objects to +represent a sequence of bytes and associated utility classes for situations +when a raw byte array is not appropriate. + +Specifically, it provides a `ByteSequence` interface, analogous to Java's +`CharSequence`, an immutable `Bytes` implementation analogous to Java's +`String`, and a corresponding `BytesBuilder` analogous to Java's +`StringBuilder`. + +The provided classes have appropriate methods for serialization, and proper +equals and hashCode implementations, as well as a comparator for +`ByteSequence`, so they will be suitable for use in `Set`s and as keys in +`Map`s. + +An immutable bytes implementation makes it possible to pass data between APIs +without the need for performance-killing protective copies. This benefit is +compounded if this library is used by multiple projects, as the need to make +protective copies while passing data between a project and its dependency's API +is eliminated. + +This project aims to provide a fluent and intuitive API, with support for +conversions to/from other common types, such as `ByteBuffer`, `byte[]`, and +`CharSequence`/`String`. + +This project requires at least Java 8, and supports `Stream` and functional +APIs where appropriate. + +See this [blog post][blog] for some additional background. + +## Safe for APIs + +Using an external library in a project's API poses some risks to that project, +especially if it and its dependencies depend on different versions of that +library. This project attempts to mitigate those risks, so that it can be used +safely by other projects. + +This project is made safe for reuse in other projects' APIs by adopting the +following principles: + +* Using [Semantic Versioning 2.0.0][semver] to make strong declarations about + backwards-compatibility +* Strongly avoid breaking changes (avoid major version bumps), so that projects + can converge on the latest version required by their code and that of their Review comment: Made some additional tweaks to the wording to address these, but avoided including "Fluo Bytes" redundantly everywhere. This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org With regards, Apache Git Services
[GitHub] ctubbsii commented on a change in pull request #1: Provide initial README
ctubbsii commented on a change in pull request #1: Provide initial README URL: https://github.com/apache/fluo-bytes/pull/1#discussion_r132544784 ## File path: README.md ## @@ -0,0 +1,102 @@ + + +# Apache Fluo Bytes + +[![Build Status][ti]][tl] [![Apache License][li]][ll] [![Maven Central][mi]][ml] [![Javadoc][ji]][jl] + +**Apache Fluo Bytes is an API project with the goal of providing an extremely +stable library for handling bytes, suitable for use in [Apache Fluo][fluo] and +other projects' APIs.** + +## Features and Goals + +This project aims to fill a void in Java, by providing convenient objects to +represent a string of bytes and associated utility classes for situations when +a raw byte array is not appropriate. + +Specifically, it provides a `ByteSequence` interface, analogous to Java's +`CharSequence`, an immutable `Bytes` implementation analogous to Java's +`String`, and a corresponding `BytesBuilder` analogous to Java's +`StringBuilder`. + +The provided classes have appropriate methods for serialization, and proper +equals and hashCode implementations, as well as a comparator for +`ByteSequence`, so they will be suitable for use in `Set`s and as keys in +`Map`s. + +An immutable bytes implementation makes it possible to pass data between APIs +without the need for performance-killing protective copies. This benefit is +compounded if this library is used by multiple projects, as the need to make +protective copies while passing data between a project and its dependency's API +is eliminated. + +This project aims to provide a fluent and intuitive API, with support for +conversions to/from other common types, such as `ByteBuffer`, `byte[]`, and +`CharSequence`/`String`. + +This project requires at least Java 8, and supports `Stream` and functional +APIs where appropriate. + +See this [blog post][blog] for some additional background. + +## Safe for APIs + +Using an external library in a project's API poses some risks to that project, +especially if it and its dependencies depend on different versions of that +library. This project attempts to mitigate those risks, so that it can be used +safely by other projects. + +This project is made safe for reuse in other projects' APIs by adopting the +following principles: + +* Using [Semantic Versioning 2.0.0][semver] to make strong declarations about + backwards-compatibility +* Strongly avoid breaking changes (avoid major version bumps), so that projects Review comment: Yeah, removal is not explicitly mentioned, but if it's "dangerous" or if a "better alternative exists", it seems appropriate to assume it is "subject to" removal, even if removal is deferred indefinitely because of other factors (stability). Part of the problem with the new flag is that "subject to" is not well-defined. I hear "subject to" and think "could possibly be, at the determination of the developers"... but that's basically *always the case*. This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org With regards, Apache Git Services
[GitHub] ctubbsii commented on a change in pull request #1: Provide initial README
ctubbsii commented on a change in pull request #1: Provide initial README URL: https://github.com/apache/fluo-bytes/pull/1#discussion_r132365844 ## File path: README.md ## @@ -0,0 +1,102 @@ + + +# Apache Fluo Bytes + +[![Build Status][ti]][tl] [![Apache License][li]][ll] [![Maven Central][mi]][ml] [![Javadoc][ji]][jl] + +**Apache Fluo Bytes is an API project with the goal of providing an extremely +stable library for handling bytes, suitable for use in [Apache Fluo][fluo] and +other projects' APIs.** + +## Features and Goals + +This project aims to fill a void in Java, by providing convenient objects to +represent a string of bytes and associated utility classes for situations when +a raw byte array is not appropriate. + +Specifically, it provides a `ByteSequence` interface, analogous to Java's +`CharSequence`, an immutable `Bytes` implementation analogous to Java's +`String`, and a corresponding `BytesBuilder` analogous to Java's +`StringBuilder`. + +The provided classes have appropriate methods for serialization, and proper +equals and hashCode implementations, as well as a comparator for +`ByteSequence`, so they will be suitable for use in `Set`s and as keys in +`Map`s. + +An immutable bytes implementation makes it possible to pass data between APIs +without the need for performance-killing protective copies. This benefit is +compounded if this library is used by multiple projects, as the need to make +protective copies while passing data between a project and its dependency's API +is eliminated. + +This project aims to provide a fluent and intuitive API, with support for +conversions to/from other common types, such as `ByteBuffer`, `byte[]`, and +`CharSequence`/`String`. + +This project requires at least Java 8, and supports `Stream` and functional +APIs where appropriate. + +See this [blog post][blog] for some additional background. + +## Safe for APIs + +Using an external library in a project's API poses some risks to that project, +especially if it and its dependencies depend on different versions of that +library. This project attempts to mitigate those risks, so that it can be used +safely by other projects. + +This project is made safe for reuse in other projects' APIs by adopting the +following principles: + +* Using [Semantic Versioning 2.0.0][semver] to make strong declarations about + backwards-compatibility +* Strongly avoid breaking changes (avoid major version bumps), so that projects Review comment: Ugh, I hate that new "feature" to Java 9, especially since it defaults to "false". Personally, I think all deprecations are subject to removal. I really don't want to start putting "forRemoval = true" in all my deprecation annotations just so users don't think "this isn't going away". I'd rather they'd have created a new annotation for things which are expected to remain, but should not be used by users, which generated similar compiler warnings as Deprecated. This one is really going to cause confusion with defaulting to false. A lot of them are going to be set to false simply because nobody's explicitly setting them to true. Users are going to be disappointed when they disappear. This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org With regards, Apache Git Services
[GitHub] ctubbsii commented on a change in pull request #1: Provide initial README
ctubbsii commented on a change in pull request #1: Provide initial README URL: https://github.com/apache/fluo-bytes/pull/1#discussion_r132365435 ## File path: README.md ## @@ -0,0 +1,102 @@ + + +# Apache Fluo Bytes + +[![Build Status][ti]][tl] [![Apache License][li]][ll] [![Maven Central][mi]][ml] [![Javadoc][ji]][jl] + +**Apache Fluo Bytes is an API project with the goal of providing an extremely +stable library for handling bytes, suitable for use in [Apache Fluo][fluo] and +other projects' APIs.** + +## Features and Goals + +This project aims to fill a void in Java, by providing convenient objects to +represent a string of bytes and associated utility classes for situations when +a raw byte array is not appropriate. Review comment: I did try to write more on this initially, but everything I came up with was too long and seemed to drift off topic. I boiled it down to what you see here, mentioning this library is useful when byte arrays aren't appropriate, and then immediately following that statement by some of the features that make it so, naming all of the things you list here. I don't know that I'd really want more details in the README than that. I certainly don't want to repeat a blog post, or make the README a big wall of text that provides so many details, it's hard to get the gist. But, if you have specific suggestions which can improve this, I'm happy to work it in. I, however, am near my editing limit on this subject. :) This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org With regards, Apache Git Services
[GitHub] ctubbsii commented on a change in pull request #1: Provide initial README
ctubbsii commented on a change in pull request #1: Provide initial README URL: https://github.com/apache/fluo-bytes/pull/1#discussion_r132364598 ## File path: README.md ## @@ -0,0 +1,102 @@ + + +# Apache Fluo Bytes + +[![Build Status][ti]][tl] [![Apache License][li]][ll] [![Maven Central][mi]][ml] [![Javadoc][ji]][jl] + +**Apache Fluo Bytes is an API project with the goal of providing an extremely +stable library for handling bytes, suitable for use in [Apache Fluo][fluo] and +other projects' APIs.** + +## Features and Goals + +This project aims to fill a void in Java, by providing convenient objects to +represent a string of bytes and associated utility classes for situations when Review comment: Fixed. This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org With regards, Apache Git Services
[GitHub] ctubbsii commented on a change in pull request #1: Provide initial README
ctubbsii commented on a change in pull request #1: Provide initial README URL: https://github.com/apache/fluo-bytes/pull/1#discussion_r132364588 ## File path: README.md ## @@ -0,0 +1,102 @@ + + +# Apache Fluo Bytes + +[![Build Status][ti]][tl] [![Apache License][li]][ll] [![Maven Central][mi]][ml] [![Javadoc][ji]][jl] + +**Apache Fluo Bytes is an API project with the goal of providing an extremely +stable library for handling bytes, suitable for use in [Apache Fluo][fluo] and Review comment: I didn't see your exact wording above, because it didn't show correctly when I saw this comment in my email, but I pushed a change which basically applies the same fix, based on your feedback above the blockquote section. This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org With regards, Apache Git Services
