gouqi 0.20.0

Rust interface for Jira
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

# gouqi

[![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](LICENSE)
[![Released API docs](https://img.shields.io/docsrs/gouqi/latest)](http://docs.rs/gouqi)
[![Rust](https://github.com/wunderfrucht/gouqi/actions/workflows/rust.yml/badge.svg)](https://github.com/wunderfrucht/gouqi/actions/workflows/rust.yml)
[![codecov](https://codecov.io/gh/wunderfrucht/gouqi/branch/main/graph/badge.svg?token=uAQXWlybzJ)](https://codecov.io/gh/wunderfrucht/gouqi)

> a rust interface for [jira](https://www.atlassian.com/software/jira)

Forked from goji <https://github.com/softprops/goji>

## install

Add the following to your `Cargo.toml` file

```toml
[dependencies]
gouqi = "*"

# Optional: Enable async API
gouqi = { version = "*", features = ["async"] }
```

## usage

Please browse the [examples](examples/) directory in this repo for some example applications.

### 🚀 Jira V3 API Migration

gouqi automatically handles the Jira V3 API transition! Your existing code continues to work seamlessly:

```rust
// Works on both V2 and V3 automatically - no code changes needed!
let results = jira.search().list("project = TEST", &Default::default())?;
```

For advanced field control and migration details, see the [**Jira V3 Migration Guide**](JIRA_V3_MIGRATION_GUIDE.md).

Basic usage requires a jira host, and a flavor of `jira::Credentials` for authorization.

### Synchronous API

The default API uses synchronous requests:

```rust,skeptic-template
use gouqi::{Credentials, Jira};
use std::env;
use tracing::error;

fn main() { 
    if let Ok(host) = env::var("JIRA_HOST") {
        let query = env::args().nth(1).unwrap_or("order by created DESC".to_owned());
        let jira = Jira::new(host, Credentials::Anonymous).expect("Error initializing Jira");

        match jira.search().iter(query, &Default::default()) {
            Ok(results) => {
                for issue in results {
                    println!("{:#?}", issue);
                }
            }
            Err(err) => panic!("{:#?}", err),
        }
    } else {
        error!("Missing environment variable JIRA_HOST!");
    }
}
```

### Asynchronous API

With the `async` feature enabled, you can use the asynchronous API:

```rust
use futures::stream::StreamExt;
use gouqi::{Credentials, SearchOptions};
use std::env;
use tracing::error;

#[tokio::main]
async fn main() {
    if let Ok(host) = env::var("JIRA_HOST") {
        let query = env::args().nth(1).unwrap_or("order by created DESC".to_owned());
        
        // Create an async Jira client
        let jira = gouqi::r#async::Jira::new(host, Credentials::Anonymous)
            .expect("Error initializing Jira");

        // Use the stream method to get a futures Stream
        let search_options = SearchOptions::default();
        match jira.search().stream(query, &search_options).await {
            Ok(mut stream) => {
                // Consume the stream asynchronously
                while let Some(issue) = stream.next().await {
                    println!("{:#?}", issue);
                }
            }
            Err(err) => error!("{:#?}", err),
        }
    } else {
        error!("Missing environment variable JIRA_HOST!");
    }
}
```

You can also convert between sync and async clients:

```rust
// Convert from sync to async
let sync_jira = Jira::new(host, credentials)?;
let async_jira = sync_jira.into_async();

// Convert from async to sync
let async_jira = gouqi::r#async::Jira::new(host, credentials)?;
let sync_jira = gouqi::sync::Jira::from(&async_jira);
```

## Commiting a PR

Please make sure to run `cargo fmt`, `cargo test` and `cargo clippy` before committing.
New code should contains tests.
Commits to follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.

Changelog is generated using [git cliff](https://github.com/orhun/git-cliff)

```sh
cargo install git-cliff
git cliff -o --use-branch-tags
```

## what's with the name

Jira's name is a [shortened form of gojira](https://en.wikipedia.org/wiki/Jira_(software)),
another name for godzilla. Goji is a play on that.

[Goji](https://en.wikipedia.org/wiki/Goji) (Chinese: 枸杞; pinyin: gǒuqǐ)

Doug Tangren (softprops) 2016-2018