Prepare v1.0.0 release

Author: preciz

.github/dependabot.yml

@@ -1,5 +1,9 @@
 version: 2
 updates:
+- package-ecosystem: github-actions
+  directory: "/"
+  schedule:
+    interval: weekly
 - package-ecosystem: mix
   directory: "/"
   schedule:

.github/workflows/test.yml

@@ -3,38 +3,72 @@ name: test
 on:
   pull_request:
   push:
-      branches:
+    branches:
       - master
+  workflow_dispatch:
+
+permissions:
+  contents: read
 
 jobs:
   mix_test:
-    name: mix test (OTP ${{matrix.otp}} | Elixir ${{matrix.elixir}})
-
-    env:
-      MIX_ENV: test
+    name: mix test (OTP ${{ matrix.otp }} | Elixir ${{ matrix.elixir }})
 
     strategy:
+      fail-fast: false
       matrix:
         include:
-          - elixir: 1.14.3
-            otp: 25.1
-            lint: true
-            installer: true
+          - elixir: "1.14"
+            otp: "25"
+          - elixir: "1.20"
+            otp: "29"
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7.0.1
+
+      - name: Set up Elixir
+        uses: erlef/setup-beam@v1.24.1
+        with:
+          elixir-version: ${{ matrix.elixir }}
+          otp-version: ${{ matrix.otp }}
+
+      - name: Install test dependencies
+        run: MIX_ENV=test mix deps.get
 
+      - name: Compile with warnings as errors
+        run: MIX_ENV=test mix compile --warnings-as-errors
 
+      - name: Run tests
+        run: MIX_ENV=test mix test
+
+  release_checks:
+    name: release checks
     runs-on: ubuntu-latest
 
     steps:
-    - name: Checkout
-      uses: actions/checkout@v3
-    - name: Set up Elixir
-      uses: erlef/setup-beam@v1
-      with:
-        elixir-version: ${{matrix.elixir}}
-        otp-version: ${{matrix.otp}}
-
-    - name: Install Dependencies
-      run: mix deps.get --only test
-
-    - name: Run Tests
-      run: mix test
+      - name: Checkout
+        uses: actions/checkout@v7.0.1
+
+      - name: Set up Elixir
+        uses: erlef/setup-beam@v1.24.1
+        with:
+          elixir-version: "1.20"
+          otp-version: "29"
+
+      - name: Install development dependencies
+        run: mix deps.get
+
+      - name: Check formatting
+        run: mix format --check-formatted
+
+      - name: Compile with warnings as errors
+        run: mix compile --warnings-as-errors
+
+      - name: Build documentation
+        run: mix docs
+
+      - name: Build Hex package
+        run: mix hex.build --output /tmp/abit-1.0.0.tar

CHANGELOG.md

@@ -1,11 +1,13 @@
 # Changelog for Abit
 
-## Unreleased
+## v1.0.0 - 2026-08-20
 
+  * Stability - Declared the existing public API stable for the first major release.
+  * Breaking - Raised the minimum supported versions to Elixir 1.14 and OTP 25.
   * Performance - Reduced overhead in bit-array set operations, atomics membership checks, and packed-counter access.
   * Fix - Added explicit validation and errors for malformed atomics serialization payloads.
   * Tests - Added property-based coverage for bitmasks, atomics operations and serialization, and packed counters.
-  * Documentation - Updated installation instructions, package metadata, and Erlang documentation links.
+  * Documentation - Updated installation instructions, package metadata, Erlang documentation links, and the 64-bit bitmask contract.
 
 ## v0.4.0
   * Feature - Added fast atomics resetting via `Abit.clear/1` and `Abit.Counter.clear/1`.

README.md

@@ -8,14 +8,14 @@ See the [API documentation](https://hexdocs.pm/abit) on HexDocs.
 
 ## Installation
 
-Abit requires Elixir 1.7 or later and OTP 21.2.1 or later.
+Abit requires Elixir 1.14 or later and OTP 25 or later.
 
 Add `abit` to your list of dependencies in `mix.exs`:
 
 ```elixir
 def deps do
   [
-    {:abit, "~> 0.4"}
+    {:abit, "~> 1.0"}
   ]
 end
 ```
@@ -60,6 +60,11 @@ Operations that write to an `:atomics` reference mutate it in place. See the
 * `Abit.Counter.get_all_at_atomic/2` - Returns all counters packed into the atomics element at the given index.
 
 ### Abit.Bitmask - helper functions for bitmasks
+
+Population counts and Hamming distances cover only the lowest 64 bits. Indexed
+operations can address higher bit positions, while `to_list/2` uses its explicit
+size argument.
+
 * `Abit.Bitmask.set_bits_count/1` - Returns the number of bits set to 1 in the given integer.
 * `Abit.Bitmask.bit_at/2` - Returns the bit at a given position in the given integer.
 * `Abit.Bitmask.set_bit_at/3` - Sets a bit in the given integer at the given position to a given bit (0 or 1).

lib/abit/bitmask.ex

@@ -1,13 +1,24 @@
 defmodule Abit.Bitmask do
   @moduledoc """
   Functions for working with bits and integer bitmasks.
+
+  `set_bits_count/1` and `hamming_distance/2` treat integers as 64-bit
+  bitmasks: they inspect bits 0 through 63 and ignore higher bits. Negative
+  integers are interpreted using their lowest 64 two's-complement bits.
+
+  The indexed operations are not capped at 64 bits, and `to_list/2` uses the
+  explicit size supplied by the caller.
   """
 
   import Bitwise
 
   @doc """
   Returns the count of bits set to 1 in the given integer `int`.
 
+  Only the lowest 64 bits are counted. Bits above bit 63 are ignored, and
+  negative integers are interpreted using their lowest 64 two's-complement
+  bits.
+
   ## Examples
 
       iex> Abit.Bitmask.set_bits_count(3)
@@ -19,21 +30,22 @@ defmodule Abit.Bitmask do
       iex> Abit.Bitmask.set_bits_count(1023)
       10
   """
-  @popcount_table (for i <- 0..255,
-                        do:
-                          for(<<b::1 <- <<i::8>> >>, b == 1, reduce: 0, do: (acc -> acc + 1)))
+  @popcount_table for(
+                    i <- 0..255,
+                    do: for(<<(b::1 <- <<i::8>>)>>, b == 1, reduce: 0, do: (acc -> acc + 1))
+                  )
                   |> List.to_tuple()
 
   @spec set_bits_count(integer) :: non_neg_integer
   def set_bits_count(int) when is_integer(int) do
     elem(@popcount_table, int &&& 255) +
-      elem(@popcount_table, (int >>> 8) &&& 255) +
-      elem(@popcount_table, (int >>> 16) &&& 255) +
-      elem(@popcount_table, (int >>> 24) &&& 255) +
-      elem(@popcount_table, (int >>> 32) &&& 255) +
-      elem(@popcount_table, (int >>> 40) &&& 255) +
-      elem(@popcount_table, (int >>> 48) &&& 255) +
-      elem(@popcount_table, (int >>> 56) &&& 255)
+      elem(@popcount_table, int >>> 8 &&& 255) +
+      elem(@popcount_table, int >>> 16 &&& 255) +
+      elem(@popcount_table, int >>> 24 &&& 255) +
+      elem(@popcount_table, int >>> 32 &&& 255) +
+      elem(@popcount_table, int >>> 40 &&& 255) +
+      elem(@popcount_table, int >>> 48 &&& 255) +
+      elem(@popcount_table, int >>> 56 &&& 255)
   end
 
   @doc """
@@ -101,6 +113,10 @@ defmodule Abit.Bitmask do
   Returns the bitwise Hamming distance between the
   given integers `int_l` and `int_r`.
 
+  The distance covers only the lowest 64 bits. Bits above bit 63 are ignored,
+  and negative integers are interpreted using their lowest 64
+  two's-complement bits.
+
   ## Examples
 
       iex> Abit.Bitmask.hamming_distance(1, 1)

mix.exs

@@ -1,15 +1,15 @@
 defmodule Abit.MixProject do
   use Mix.Project
 
-  @version "0.4.0"
+  @version "1.0.0"
   @github "https://github.com/preciz/abit"
 
   def project do
     [
       app: :abit,
       name: "Abit",
       version: @version,
-      elixir: "~> 1.7",
+      elixir: "~> 1.14",
       start_permanent: Mix.env() == :prod,
       deps: deps(),
       docs: docs(),

test/abit/bitmask_test.exs

@@ -92,7 +92,7 @@ defmodule Abit.BitmaskTest do
       assert Bitmask.set_bit_at(10, -1, 1) == 10
       assert Bitmask.set_bit_at(10, -1, 0) == 10
     end
-    
+
     test "hamming_distance with integers larger than 64 bits" do
       # Since it uses set_bits_count, it also ignores bits above 64.
       assert Bitmask.hamming_distance(1 <<< 65, 0) == 0

test/abit/counter_test.exs

@@ -141,7 +141,7 @@ defmodule Abit.CounterTest do
     counter = Counter.new(10, 8)
     tasks = for i <- 1..8, do: Task.async(fn -> Counter.add(counter, i, 1) end)
     Enum.each(tasks, &Task.await/1)
-    for i <- 1..8, do: assert Counter.get(counter, i) == 1
+    for i <- 1..8, do: assert(Counter.get(counter, i) == 1)
   end
 
   test "put/3 preserves concurrent writes to counters in the same atomics integer" do
@@ -170,17 +170,17 @@ defmodule Abit.CounterTest do
     refute Enum.member?(counter, 101)
 
     assert Enum.max(counter) == 100
-    
+
     # This covers `do_reduce` with `{:halt, acc}` and `fun` invocation
     assert Enum.take(counter, 4) == [0, 42, 0, 100]
-    
+
     # This covers `do_reduce` reaching the `done` state
     assert Enum.sum(counter) == 142
     assert Enum.to_list(counter) |> length() == 16
 
     # This covers `do_slice` function via `Enum.slice`
     assert Enum.slice(counter, 1..3) == [42, 0, 100]
-    
+
     # This covers `do_reduce` with `{:suspend, acc}`
     assert Enum.zip(counter, [1, 2, 3]) |> Enum.to_list() == [{0, 1}, {42, 2}, {0, 3}]
   end
@@ -192,14 +192,14 @@ defmodule Abit.CounterTest do
         Counter.new(0, 8)
       end
     end
-    
+
     test "put with negative value when wrap_around is true" do
       c = Counter.new(10, 8, wrap_around: true, signed: false)
       # -1 wrapping around in 8-bit unsigned becomes 255
       assert {:ok, {0, 255}} = Counter.put(c, 0, -1)
       assert Counter.get(c, 0) == 255
     end
-    
+
     test "add with very large increment wrapping around multiple times" do
       c = Counter.new(10, 8, wrap_around: true, signed: false)
       # 256 + 10 = 266 -> wraps around 256 to 10

test/abit_test.exs

@@ -27,7 +27,7 @@ defmodule AbitTest do
     ref_a |> :atomics.put(1, 321)
     ref_b |> :atomics.put(2, 123)
 
-    merged_ref = Abit.merge(ref_a, ref_b)
+    merged_ref = apply(Abit, :merge, [ref_a, ref_b])
     assert merged_ref == ref_a
     assert 321 = :atomics.get(merged_ref, 1)
     assert 123 = :atomics.get(merged_ref, 2)
@@ -307,14 +307,14 @@ defmodule AbitTest do
 
   test "set_bit_at/3 concurrently for different bits" do
     ref = :atomics.new(1, signed: false)
-    
+
     # Spawn tasks that toggle bit 0 concurrently to create contention on the atomics integer
     toggle_tasks = for _ <- 1..500, do: Task.async(fn -> Abit.toggle_bit_at(ref, 63) end)
-    
+
     tasks = for i <- 0..50, do: Task.async(fn -> Abit.set_bit_at(ref, i, 1) end)
-    
+
     Enum.each(toggle_tasks ++ tasks, &Task.await/1)
-    
+
     # All bits 0..50 should be set
     for i <- 0..50 do
       assert Abit.bit_at(ref, i) == 1
@@ -327,7 +327,7 @@ defmodule AbitTest do
     tasks = for _ <- 1..500, do: Task.async(fn -> Abit.toggle_bit_at(ref, 0) end)
     Enum.each(tasks, &Task.await/1)
     assert :atomics.get(ref, 1) == 0
-    
+
     # Toggling 501 times should result in the bit being set to 1.
     tasks = for _ <- 1..501, do: Task.async(fn -> Abit.toggle_bit_at(ref, 0) end)
     Enum.each(tasks, &Task.await/1)