From 88c16ad0060b938054e6035347f02499e4c11287 Mon Sep 17 00:00:00 2001
From: Wouter van der Plas <2423856+wvanderp@users.noreply.github.com>
Date: Tue, 24 Dec 2024 02:40:42 +0100
Subject: [PATCH] Update deployment instructions and enhance README for clarity
 and features

---
 DEPLOY.md |  9 +++++++--
 README.md | 52 ++++++++++++++++++++++++++++++++++++----------------
 2 files changed, 43 insertions(+), 18 deletions(-)

diff --git a/DEPLOY.md b/DEPLOY.md
index 033df5b..fa6eebf 100644
--- a/DEPLOY.md
+++ b/DEPLOY.md
@@ -10,7 +10,12 @@ See if the results are acceptable. Then, push the result to Github.
 
 ## Tagging
 
-* Then tag a new version on Github
-* Increment the minor or the build number
+* Create tag a new version on Github
+  * The tag should be in the format `vX.Y.Z` where X is the major version, Y is the minor version, and Z is the build number
+  * Increment the minor or the build number
 * Write the change notes
 * When the tag is saved, Github actions will trigger a build and upload to npm, and the building of the new documentation
+
+## Automatic Release
+
+When a new release tag is published, the workflow checks out code, installs Node.js 20, updates package.json to the release tag, builds and tests, then automatically publishes to npm and pushes the version bump back to GitHub.
diff --git a/README.md b/README.md
index e42e23f..778dac7 100644
--- a/README.md
+++ b/README.md
@@ -5,58 +5,78 @@
 [![codecov](https://codecov.io/gh/wvanderp/iwf/branch/main/graph/badge.svg?token=6CPZPAOAUP)](https://codecov.io/gh/wvanderp/iwf)
 [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fwvanderp%2Fiwf.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fwvanderp%2Fiwf?ref=badge_shield)
 
-A better way of working with the wikidata
+A TypeScript library that simplifies working with Wikidata through an intuitive object-oriented interface.
+Wikidata is a free knowledge base that anyone can edit, serving as a central storage for structured data used by Wikipedia and other Wikimedia projects.
 
 ## Features
 
-- Request items from wikidata
-- Work with wikidata using classes
-- Upload the changes back to wikidata
+- Request and parse Wikidata items
+- Object-oriented interface for working with Wikidata entities
+- Full TypeScript support with comprehensive type definitions
+- Upload changes back to Wikidata with automatic diff generation
+- Handle labels, descriptions, aliases, statements, and sitelinks
+- Support for both anonymous and authenticated operations
 
-## Getting Started
+## Requirements
+
+- Node.js 16 or higher
+- For browser usage: Modern browsers supporting ES2020+
+- For authenticated operations: A Wikidata account
+
+## Installation
 
 ```bash
 npm i --save iwf
 ```
 
-You can easily request an item from wikidata and list all the labels.
+You can easily request an item from Wikidata and list all the labels. For example, Q42 represents Douglas Adams in Wikidata:
 
 ```typescript
-import {requestItem} from 'iwf';
+import { requestItem } from 'iwf';
 
-const item = requestItem('Q42');
+// Request the item for Douglas Adams (Q42)
+const item = await requestItem('Q42');
 
+// Prints all available labels in different languages
 console.log(item.labels);
 ```
 
-Or create a new item and upload it to wikidata.
+Create a new item and upload it to Wikidata. This example creates a new astronomical object:
 
 ```typescript
 import { Item, getToken, upload, Label, Statement, WikibaseItemSnak } from 'iwf';
 
 const item = Item.fromNothing();
 
-item.labels.push(Label.fromString('en', 'new planet '));
+// Add an English label
+item.labels.push(Label.fromString('en', 'new planet'));
+
+// Add a statement: instance of (P31) celestial body (Q634)
 item.statements.push(Statement.fromSnak(WikibaseItemSnak.fromID('P31', 'Q634')));
 
-const token = await getToken('your wikidata username', 'your wikidata password');
+// Authenticate and upload
+const token = await getToken('your Wikidata username', 'your Wikidata password');
 
-upload(item, {
-    summary: 'test update',
+await upload(item, {
+    summary: 'Adding new astronomical object',
     authToken: token
 });
 ```
 
+## Authentication
+
+The library supports both authenticated and anonymous operations. For editing operations, you'll need a Wikidata account. Anonymous operations are limited to reading data.
+
 ## Documentation
 
-To see all the functionality, extra documentation, and examples, visit [the documentation](https://wvanderp.github.io/iwf/)
+To see all the functionality, extra documentation, and examples, visit [the documentation](https://wvanderp.github.io/iwf/).
 
 ## Where can you help?
 
 You are already helping by using this library, but if you want to do more, there are a few things you can do:
 
-- If you find a bug, please report it here on github.
-- If you have an idea for a new feature, please create an issue here on github.
+- If you find a bug, please report it here on GitHub.
+- If you have an idea for a new feature, please create an issue here on GitHub.
 - If you want to help with the development, you can fork this repository and create a pull request.
 
 There is a [FUTURE.md](FUTURE.md) file that contains ideas for future development. If you want to help, you can look there for ideas.