Deprecated include_draft method

Author: sunil-lakshman

.gitignore

@@ -4,6 +4,7 @@ test
 doc
 spec-integration
 coverage
+spec/.env.test
 \.yardoc
 .DS_Store
 .bundle/

CHANGELOG.md

@@ -1,5 +1,10 @@
 ## CHANGELOG
 
+## Version 0.8.5
+### Date: 5th-June-2026
+ ### Deprecated
+ - `Query#include_draft` is deprecated. The Content Delivery API returns published content only; the `include_draft` query parameter has no effect. Use Live Preview with the Preview Service to preview unpublished entries, or the Content Management API to work with draft content.
+
 ## Version 0.8.4
 ### Date: 15th-April-2026
  ### Security and Compatibility

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    contentstack (0.8.4)
+    contentstack (0.8.5)
       activesupport (>= 3.2)
       contentstack_utils (~> 1.2)
 
@@ -39,12 +39,12 @@ GEM
     hashdiff (1.2.1)
     i18n (1.14.8)
       concurrent-ruby (~> 1.0)
-    json (2.19.4)
+    json (2.19.5)
     logger (1.7.0)
-    minitest (6.0.5)
+    minitest (6.0.6)
       drb (~> 2.0)
       prism (~> 1.5)
-    nokogiri (1.19.2-arm64-darwin)
+    nokogiri (1.19.3-arm64-darwin)
       racc (~> 1.4)
     prism (1.9.0)
     public_suffix (7.0.5)
@@ -77,7 +77,7 @@ GEM
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
-    yard (0.9.43)
+    yard (0.9.44)
 
 PLATFORMS
   arm64-darwin-22

lib/contentstack/query.rb

@@ -565,16 +565,19 @@ def include_embedded_items()
       self
     end
 
-    # Include objects in 'Draft' mode in response
-    #
-    # Example
-    #
-    #    @query = @stack.content_type('product').query
-    #    @query.include_draft
-    #
-    # @return [Contentstack::Query]
-    def include_draft(flag=true)
-      @query[:include_draft] = flag
+    # @deprecated since 0.8.5 The Content Delivery API returns published content only.
+    #   Unpublished or draft entries are not available through CDA queries. Use Live Preview
+    #   with the Preview Service, or the Content Management API, to access unpublished content.
+    #
+    # @return [Contentstack::Query]
+    def include_draft(_flag=true)
+      warn(
+        "Contentstack: Query#include_draft is deprecated and has no effect on the Content " \
+        "Delivery API, which returns published content only. To preview unpublished entries, " \
+        "use Live Preview with the Preview Service. To manage or fetch draft entries, use " \
+        "the Content Management API.",
+        uplevel: 1
+      )
       self
     end
 

lib/contentstack/version.rb

@@ -1,3 +1,3 @@
 module Contentstack
-  VERSION = "0.8.4"
+  VERSION = "0.8.5"
 end

skills/testing/SKILL.md

@@ -30,7 +30,7 @@ description: Use when writing or fixing RSpec examples, WebMock stubs, JSON fixt
 
 ### Helpers
 
-- **`create_client`** and **`create_preview_client`** in **`spec_helper`** build clients using **`ENV['API_KEY']`**, **`ENV['DELIVERY_TOKEN']`**, **`ENV['ENVIRONMENT']`** — tests should not rely on real credentials; stubs supply responses.
+- **`create_client`** and **`create_preview_client`** in **`spec_helper`** build clients using **`ENV['API_KEY']`**, **`ENV['DELIVERY_TOKEN']`**, **`ENV['ENVIRONMENT']`**. Copy **`spec/.env.test.example`** to **`spec/.env.test`** (gitignored) for local runs without exporting env vars; CLI/env values already set take precedence. Tests use WebMock stubs and do not require live API calls.
 
 ### Coverage
 

spec/.env.test.example

@@ -0,0 +1,10 @@
+# Copy to spec/.env.test and fill in your stack credentials.
+# spec/.env.test is gitignored — do not commit real tokens.
+#
+# bundle exec rspec
+
+API_KEY=your_stack_api_key
+DELIVERY_TOKEN=your_delivery_token
+ENVIRONMENT=development
+# Optional: only needed for custom CDN host tests
+# HOST=cdn.contentstack.io

spec/query_spec.rb

@@ -165,8 +165,13 @@
     expect(data.first.fields[:locale]).not_to be nil
   end
 
-  it "should get data using `include_draft` method" do
-    data = category_query.include_draft.fetch
+  it "warns when `include_draft` is called and does not send include_draft to the API" do
+    query = category_query
+    expect {
+      query.include_draft
+    }.to output(/Query#include_draft is deprecated/).to_stderr
+    expect(query.query).not_to have_key(:include_draft)
+    data = query.fetch
     expect(data.length).to eq 5
   end
 

spec/spec_helper.rb

@@ -16,6 +16,8 @@
 require 'webmock/rspec'
 WebMock.disable_net_connect!(allow_localhost: true)
 
+require_relative 'support/load_test_env'
+
 require 'simplecov'
 SimpleCov.start
 

spec/support/load_test_env.rb

@@ -0,0 +1,23 @@
+# Loads optional local test credentials from spec/.env.test (gitignored).
+# Existing ENV values are not overwritten, so CLI exports still take precedence.
+module ContentstackTestEnv
+  ENV_FILE = File.expand_path("../.env.test", __dir__).freeze
+
+  def self.load!
+    return unless File.file?(ENV_FILE)
+
+    File.foreach(ENV_FILE) do |line|
+      line = line.strip
+      next if line.empty? || line.start_with?("#")
+
+      key, value = line.split("=", 2)
+      next if key.nil? || value.nil?
+
+      key = key.strip
+      value = value.strip.delete_prefix('"').delete_suffix('"')
+      ENV[key] = value unless ENV.key?(key) && !ENV[key].to_s.empty?
+    end
+  end
+end
+
+ContentstackTestEnv.load!