Project publishing instruction + changelog generation script (#998)

* Project publishing instruction + changelog generation script

* pre-commit change

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

docs/publishing.md

@@ -0,0 +1,70 @@
+# Publishing a New Version of Beanie
+
+This guide provides step-by-step instructions on how to prepare and publish a new version of Beanie. Before starting, ensure that you have the necessary permissions to update the repository.
+
+## 1. Prepare a New Version PR
+
+To publish a new version of Beanie, you need to create a pull request (PR) with the following updates:
+
+### 1.1 Update the Version in `pyproject.toml`
+
+1. Open the [`pyproject.toml`](https://github.com/BeanieODM/beanie/blob/main/pyproject.toml) file.
+2. Update the `version` field to the new version number.
+
+### 1.2 Update the Version in the `__init__.py` File
+
+1. Open the [`__init__.py`](https://github.com/BeanieODM/beanie/blob/main/beanie/__init__.py) file.
+2. Update the `__version__` variable to the new version number.
+
+### 1.3 Update the Changelog
+
+To update the changelog, follow these steps:
+
+#### 1.3.1 Set the Version in the Changelog Script
+
+1. Open the [`scripts/generate_changelog.py`](https://github.com/BeanieODM/beanie/blob/main/scripts/generate_changelog.py) file.
+2. Set the `current_version` to the current version and `new_version` to the new version in the script.
+
+#### 1.3.2 Run the Changelog Script
+
+1. Run the following command to generate the updated changelog:
+
+   ```bash
+   python scripts/generate_changelog.py
+   ```
+
+2. The script will generate the changelog for the new version.
+
+#### 1.3.3 Update the Changelog File
+
+1. Open the [`changelog.md`](https://github.com/BeanieODM/beanie/blob/main/docs/changelog.md) file.
+2. Copy the generated changelog and paste it at the top of the `changelog.md` file.
+
+### 1.4 Create and Submit the PR
+
+Once you have made the necessary updates, create a PR with a descriptive title and summary of the changes. Ensure that all checks pass before merging the PR.
+
+## 2. Publishing the Version
+
+After the PR has been merged, respective GH action will publish it to the PyPI.
+
+## 3. Create a Git Tag and GitHub Release
+
+After the version has been published:
+
+1. Pull the latest changes from the `master` branch:
+   ```bash
+   git pull origin master
+   ```
+
+2. Create a new Git tag with the version number:
+   ```bash
+   git tag -a v1.xx.y -m "Release v1.xx.y"
+   ```
+
+3. Push the tag to the remote repository:
+   ```bash
+   git push origin v1.xx.y
+   ```
+
+4. Create a new release on GitHub using the GitHub interface.

scripts/generate_changelog.py

@@ -0,0 +1,76 @@
+import subprocess
+from dataclasses import dataclass
+from datetime import datetime
+from typing import List
+
+import requests  # type: ignore
+
+
+@dataclass
+class PullRequest:
+    number: int
+    title: str
+    user: str
+    user_url: str
+    url: str
+
+
+class ChangelogGenerator:
+    def __init__(
+        self,
+        username: str,
+        repository: str,
+        current_version: str,
+        new_version: str,
+    ):
+        self.username = username
+        self.repository = repository
+        self.base_url = f"https://api.github.com/repos/{username}/{repository}"
+        self.current_version = current_version
+        self.new_version = new_version
+        self.commits = self.get_commits_after_tag(current_version)
+        self.prs = [self.get_pr_for_commit(commit) for commit in self.commits]
+
+    def get_commits_after_tag(self, tag: str) -> List[str]:
+        result = subprocess.run(
+            ["git", "log", f"{tag}..HEAD", "--pretty=format:%H"],
+            stdout=subprocess.PIPE,
+            text=True,
+        )
+        return result.stdout.split()
+
+    def get_pr_for_commit(self, commit_sha: str) -> PullRequest:
+        url = f"{self.base_url}/commits/{commit_sha}/pulls"
+        response = requests.get(url)
+        response.raise_for_status()
+        pr_data = response.json()[0]
+        return PullRequest(
+            number=pr_data["number"],
+            title=pr_data["title"],
+            user=pr_data["user"]["login"],
+            user_url=pr_data["user"]["html_url"],
+            url=pr_data["html_url"],
+        )
+
+    def generate_changelog(self) -> str:
+        markdown = f"\n## [{self.new_version}] - {datetime.now().strftime('%Y-%m-%d')}\n"
+        for pr in self.prs:
+            markdown += (
+                f"### {pr.title.capitalize()}\n"
+                f"- Author - [{pr.user}]({pr.user_url})\n"
+                f"- PR <{pr.url}>\n"
+            )
+        markdown += f"\n[{self.new_version}]: https://pypi.org/project/{self.repository}/{self.new_version}\n"
+        return markdown
+
+
+if __name__ == "__main__":
+    generator = ChangelogGenerator(
+        username="BeanieODM",
+        repository="beanie",
+        current_version="1.26.0",
+        new_version="1.27.0",
+    )
+
+    changelog = generator.generate_changelog()
+    print(changelog)