getting dev up to speed after first release

Merge pull request #4 from Abductcows/master

Author: George B

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,27 @@
+---
+name: Bug report
+about: Create a report to identify unintended behaviour
+title: "[BUG] - ..."
+labels: bug
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behaviour:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/design-or-implementation-improvement.md

@@ -0,0 +1,10 @@
+---
+name: Design or Implementation improvement
+about: Suggest a change to improve the internal logic or performance of the class
+title: "[Design/Implementation] - ..."
+labels: ok but this is better
+assignees: ''
+
+---
+
+

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: "[Feature Request] - ..."
+labels: feature request
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing to Java BitArray
+
+Thank you for taking an interest in this project. You can contribute by writing code to fix/extend the features or use/test the class itself. 
+
+You should start by [creating an issue](https://github.com/Abductcows/java-bit-array/issues) and relaying your idea or findings. You can find issue templates [here](https://github.com/Abductcows/java-bit-array/issues/new/choose) but using them is not mandatory. 
+
+
+### Bug reports
+
+Create an [issue](https://github.com/Abductcows/java-bit-array/issues) with the [bug](https://github.com/Abductcows/java-bit-array/labels/bug) label and state the problem. A "good" bug report usually contains:
+- A quick summary of the use case and context
+- What you expected to see
+- What actually happened
+- Steps to reproduce the unexpected behaviour if not clear
+- Code snippets, debugger messages or screenshots if appropriate
+
+### Code contributions
+
+This repository uses [Maven](https://maven.apache.org/) for project management and [SemVer 2.0](https://semver.org/) for version specification. Source file format is **UTF-8 CRLF** with **4 spaces** for indentation. Development takes place in the [dev](https://github.com/Abductcows/java-bit-array/tree/dev) branch and is eventually integrated in the next release.
+
+Before writing any code, you should state your intent by creating an [issue](https://github.com/Abductcows/java-bit-array/issues) with the appropriate tag. You could also ask to be assigned to an existing issue. Upon confirmation, follow the usual fork-pull request pattern (and increment product version):
+
+- [Fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo#fork-an-example-repository) this repository (top right corner)
+- [Clone](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository#cloning-a-repository-using-the-command-line) your new repository to your machine and make the code changes
+- **Important:** increment version number in [pom.xml](https://github.com/Abductcows/java-bit-array/blob/dev/pom.xml) and Javadoc `@version` in compliance with [SemVer 2.0](https://semver.org/)
+- [Commit and push](https://docs.github.com/en/github/managing-files-in-a-repository/adding-a-file-to-a-repository-using-the-command-line) your changes to your forked repository
+- [Create a pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request#creating-the-pull-request) from your repository's dev branch to this repository.
+
+Please note that pull requests which do not comply with the rules aforementioned or make unnecessary whitespace modifications at unrelated locations will not be admitted unless revised. 
+
+### License
+
+By contributing to this repository, you agree that your contributions will be licensed under the project's license: Apache License, Version 2.0

README.md

@@ -1,5 +1,46 @@
-# java-bit-array
+# Java BitArray
 
-Java array of bit values that uses 1 bit per entry
+[![Latest release][latest-release-shield]][latest-release-url]  
+[![Open Issues][open-issues-shield]][open-issues-url]  
+[![Contributors][contributors-shield]][contributors-url]
 
-Proper readme, Javadoc and first release coming soon
+### Motivation
+This class is a replacement for the `ArrayList<Boolean>` type when working with its `List` interface. It boasts higher performance in add, remove and set operations and requires less memory for storing the same elements. 
+
+The BitArray is by all means an array; it is random access and all elements have contiguous indices at all times. Its behaviour is meant to be indistinguishable from ArrayList in order for programmers to be able to substitute it for the latter and benefit from its performance advantage. 
+
+### Few details
+Internally the array stores the boolean elements in an array of long primitives. These long primitives essentially form a sequence of bits; their chained bit representation in 2's complement. Boolean elements are converted to and from their bit equivalent to perform insertions, deletions etc. With the appropriate bitwise operations new elements can be added at a specific index and elements already in the array can be shifted to preserve the previous order. Thanks to that hack, element shifting and array resizing is much cheaper, all while the elements themselves occupy less space in memory.
+
+### Performance
+With regard to the difference in performance, I have a [temporary benchmark](https://github.com/Abductcows/java-bit-array/blob/dev/src/test/java/gr/geompokon/bitarray/BitArrayVsArrayListBenchmarkTest.java) file for you to test. I am looking into creating a more trustworthy benchmark using a benchmark framework like [JMH](https://github.com/openjdk/jmh) in order to be able to publish some results with confidence. If you have experience doing that and want to contribute, feel free to start an [issue](https://github.com/Abductcows/java-bit-array/issues).
+
+### Disclaimer
+As you can tell from the project version and creation date this class is very new and not battle-tested. As such I would discourage you from using it in a serious application just yet.
+
+# Getting Started
+You will need the class and source files. You can grab the [latest release](https://github.com/Abductcows/java-bit-array/releases/latest) (built for jdk-11) or download the project and run `mvn package/install` yourself. Releases contain a zip file with separate jars for classes, sources and javadoc. Include at least the class jar in your project and you will be able to use the BitArray. Looks like you are good to go.
+
+### Versioning
+The project uses [SemVer](https://semver.org/) for versioning.
+
+### Contributions and future of this project
+I would like to work on this project with anyone willing to contribute. My estimation of the rough priority of actions needed is:
+
+- Testing/debugging: Write better and well documented tests to enhance confidence
+- Benchmarking: Give ArrayList a run for their money
+- Optimizing: 'cause why not. Maybe override a few of the AbstractList's default implementations
+- New features: Not sure what to add, suggestions very welcome
+
+If you want to contribute, check out [CONTRIBUTING.md](https://github.com/Abductcows/java-bit-array/blob/master/CONTRIBUTING.md) for more info.
+
+### Authors
+- *George Bouroutzoglou* (geompokon@csd.auth.gr)
+
+
+[open-issues-url]: https://github.com/Abductcows/java-bit-array/issues
+[open-issues-shield]: https://img.shields.io/github/issues/abductcows/java-bit-array
+[contributors-url]: https://github.com/Abductcows/java-bit-array/graphs/contributors
+[contributors-shield]: https://img.shields.io/github/contributors/abductcows/java-bit-array
+[latest-release-shield]: https://img.shields.io/github/v/release/abductcows/java-bit-array?sort=semver
+[latest-release-url]: https://github.com/Abductcows/java-bit-array/releases/latest

pom.xml

@@ -65,9 +65,11 @@
                 <version>3.2.0</version>
                 <configuration>
                     <javadocExecutable>${java.home}/bin/javadoc</javadocExecutable>
-                    <includes>
-                        <include>${project.basedir}/LICENSE</include>
-                    </includes>
+                    <level>public</level>
+
+                    <defaultVersion>${project.version}</defaultVersion>
+                    <fixTags>version</fixTags>
+                    <force>true</force>
                 </configuration>
                 <executions>
                     <execution>

src/main/java/gr/geompokon/bitarray/BitArray.java

@@ -22,9 +22,9 @@
  * Class that models an array of {@code Booleans} with the {@link java.util.List} interface.
  *
  * <p>
- * The aim of this class is to enhance the performance of common operations such as {@code add}, {@code remove} and
- * {@code set} while also minimizing its memory footprint. This class was made explicitly to replace {@link ArrayList}
- * when working with {@code Boolean} elements.
+ * This class was made explicitly to replace {@link java.util.ArrayList} when working with {@code Boolean} elements.
+ * It aims to enhance the performance of common operations such as {@code add}, {@code remove} and {@code set} while
+ * also minimizing its memory footprint.
  * </p>
  *
  * <p>
@@ -50,7 +50,6 @@
  * not follow the one bit per entry principle.
  * </p>
  *
- * @author George Bouroutzoglou (geompokon@csd.auth.gr)
  * @version 1.0.0
  * @see java.util.List
  * @see java.util.AbstractList
@@ -79,7 +78,7 @@ public final class BitArray extends AbstractList<Boolean> implements RandomAcces
     private int elements;
 
     /**
-     * Default constructor. Sets initial capacity to {@link #DEFAULT_CAPACITY}.
+     * Default constructor. Sets initial capacity to 64
      */
     public BitArray() {
         this(DEFAULT_CAPACITY);
@@ -109,7 +108,7 @@ public BitArray(int initialCapacity) {
      * </p>
      *
      * @param other the collection supplying the elements
-     * @throws NullPointerException if the collection is null
+     * @throws java.lang.NullPointerException if the collection is null
      */
     public BitArray(Collection<? extends Boolean> other) {
         Objects.requireNonNull(other);
@@ -147,7 +146,7 @@ private void initMembers(int initialCapacity) {
      *
      * @param index array index to insert the element in
      * @param bit   the boolean value to be inserted
-     * @throws IndexOutOfBoundsException if index is out of array insertion bounds
+     * @throws java.lang.IndexOutOfBoundsException if index is out of array insertion bounds
      */
     public void add(int index, Boolean bit) {
         Objects.requireNonNull(bit);
@@ -194,7 +193,7 @@ public Boolean get(int index) {
      * @param index index of the array element to be changed
      * @param bit   the new value of the array element
      * @return boolean value of the previous bit at that index
-     * @throws IndexOutOfBoundsException if index is out of array bounds
+     * @throws java.lang.IndexOutOfBoundsException if index is out of array bounds
      */
     public Boolean set(int index, Boolean bit) {
         Objects.requireNonNull(bit);
@@ -516,9 +515,9 @@ public BitArray clone() {
      *
      * <p>
      * The string consists of the number of elements in the array and a list of the elements in a human readable
-     * format. Exact representation is "Size = SIZE, [((0 | 1) + ' ')*]" where SIZE is a non negative integer and
-     * the list of elements consists of opening square brackets ([), zero or more bits (single digit ones or zeros)
-     * separated by spaces and closing square brackets.
+     * format. Exact representation is "Size = SIZE, [(((0 | 1) + ' ')* (0 | 1))?]" where SIZE is a non negative integer
+     * and '+' is the concatenation operator. The list of elements consists of opening square brackets ([), zero or more
+     * bits (single digit ones or zeros) separated by spaces and closing square brackets.
      * </p>
      * <p>
      * Examples:<br>