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 @@
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# 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

Reply via email to