Merge pull request juju#16567 from nvinuesa/lease_mgr_docs

juju#16567

This patch adds documentation to the lease manager worker.

## Checklist

*If an item is not applicable, use `~strikethrough~`.*

- [ ] ~Code style: imports ordered, good names, simple structure, etc~
- [X] Comments saying why design decisions were made
- [ ] ~Go unit tests, with comments saying what you're testing~
- [ ] ~[Integration tests](https://github.com/juju/juju/tree/main/tests), with comments saying what you're testing~
- [ ] ~[doc.go](https://discourse.charmhub.io/t/readme-in-packages/451) added or updated in changed packages~


## Documentation changes

Adds documentation as `doc.go` comments to the `lease` worker package.

worker/lease/doc.go

@@ -0,0 +1,19 @@
+// Copyright 2023 Canonical Ltd.
+// Licensed under the AGPLv3, see LICENCE file for details.
+
+// Package lease, also known as the manager, manages the leases used by
+// individual Juju workers.
+//
+// Workers will claim a lease, and they are either attributed (i.e., the workers
+// gets the lease ) or blocked (i.e., the worker is waiting for a lease to
+// become available).
+// In the latter case, the manager will keep track of all the blocked claims.
+// When a worker's lease expires or gets revoked, then the manager will
+// re-attribute it to one of other workers, thus unblocking them and satisfying
+// their claim.
+// In the special case where a worker is upgrading an application, it will ask
+// the manager to "pin" the lease. This means that the lease will not expire or
+// be revoked during the upgrade, and the validity of the lease will get
+// refreshed once the upgrade has completed. The overall effect is that the
+// application unit does not lose leadership during an upgrade.
+package lease