You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/guide.md
+17-5Lines changed: 17 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,14 +1,14 @@
1
1
# 1. The way from [python-bugzilla](https://github.com/python-bugzilla/python-bugzilla)
2
2
3
-
## 1.1 About *MI*
3
+
## 1.1. About *MI*
4
4
5
-
### 1.1.1 WHAT
5
+
### 1.1.1. WHAT
6
6
7
7
**MI** stands for **Machine Interface**. The concept of MI originates from the well-known [GDB: The GNU Project Debugger](https://www.sourceware.org/gdb/) with docs at [GDB User Manual - The GDB/MI Interface](https://sourceware.org/gdb/current/onlinedocs/gdb/GDB_002fMI.html#GDB_002fMI).
8
8
9
9
For this project, when you run **MI** from your terminal, it starts to wait until it reads a line from `stdin`, then performs the corresponding operation, and finally writes some results and necessary information to `stdout`. Of course, these corresponding operations may also include reading some strings from `stdin`, such as obtaining the user name and password during interactive login.
10
10
11
-
### 1.1.2 WHY
11
+
### 1.1.2. WHY
12
12
13
13
[python-bugzilla](https://github.com/python-bugzilla/python-bugzilla) is undoubtedly an excellent project. It is packaged as a python library and published on [python-bugzilla - PyPI](https://pypi.org/project/python-bugzilla/). After running the installation scripts in `setup.py`, users could not only `import bugzilla` in their code, but also run `/usr/bin/bugzilla` directly in the terminal to use it through **CLI**.
14
14
@@ -20,7 +20,7 @@ Not only that, we also hope that our new interface can **not only** be friendly
20
20
21
21
All the above reminds us of [GDB/MI Interface](https://sourceware.org/gdb/current/onlinedocs/gdb/GDB_002fMI.html#GDB_002fMI). So we borrowed the concept of **MI** from here and developed what you see today: run `bugzilla-mi`, after seeing the prompt of *ArgumentParser waiting*, type just exactly the same parameters to `stdin` when running `bugzilla-cli`, then press Enter (actually a **line break** is typed in), and then continue to type something or just wait, and finally get the expected output in `stdout`. After that you will continue to see the prompt of *ArgumentParser waiting*, and then get into another new round of typing parameters.
22
22
23
-
### 1.1.3 HOW
23
+
### 1.1.3. HOW
24
24
25
25
It is easy to find that after installation running `/usr/bin/bugzilla` in terminal is exactly equivalent to running `python ./bugzilla-cli` in the project root directory of [python-bugzilla](https://github.com/python-bugzilla/python-bugzilla). And `bugzilla-cli` is actually just a wrapper of `_cli.main`. So we do the surgery on a copy of `_cli.py`, i.e., `_mi.py`. Although original `_cli.py` looks complex, it is highly cohesive and low coupling, so the surgery is easy. We
26
26
@@ -31,6 +31,18 @@ It is easy to find that after installation running `/usr/bin/bugzilla` in termin
31
31
* add a cache mechanism in `_make_bz_instance` to make a new instance when necessary;
32
32
* add many `try-except` and `raise` statements to make the round by round loop process run robustly without unexpected interruption.
33
33
34
+
## 1.2. Something shrunk
34
35
36
+
You can see that although generally we are adding sth rather than deleting, many files have been deleted compared with the original content. We will briefly explain this below to help you understand the purpose of doing so.
35
37
36
-
## 1.2 Something shrunk
38
+
### 1.2.1. setup files
39
+
40
+
The main purpose we expect is to serve as a backend of some automation control systems. In this case, we believe that installing into *site-packages* of your Python environment may be a bad choice. We expect the users to be **free to choose and control** where to place and run these scripts without the help of `pip`. Therefore, it is sufficient to provide only `bugzilla-cli` for forward compatibility and `bugzilla-mi` for daily use. If you want to import from *site-packages*, or just type `bugzilla --balabala` in your terminal and press Enter anyway, you are recommended to select the original [python-bugzilla](https://github.com/python-bugzilla/python-bugzilla).
41
+
42
+
### 1.2.2. tests, quality-checks and docs
43
+
44
+
Limited by our time and resources, these less important content has been removed. And our development does not involve changing the original code in package `bugzilla`, we only add something new. What we need to confirm is that once there is no problem in original *python-bugzilla*, the code added by us will also work well. Therefore, only things related to the newly added code are retained.
0 commit comments