Skip to content

Commit 29009e2

Browse files
thekavemanthekaveman
authored
Prep release 2022.01.1 (#15)
2 parents a27e486 + 2e5b770 commit 29009e2

File tree

3 files changed

+128
-20
lines changed

3 files changed

+128
-20
lines changed

‎.github/workflows/dotnet-test.yml

Lines changed: 0 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,8 @@
11
name: Run tests
22

33
on:
4-
push:
5-
branches: [ main ]
6-
paths:
7-
- .github/workflows/dotnet-test.yml
8-
- 'src/**'
9-
- 'tests/**'
10-
- HashFields.sln
11-
124
pull_request:
135
branches: [ "*" ]
14-
paths:
15-
- .github/workflows/dotnet-test.yml
16-
- 'src/**'
17-
- 'tests/**'
18-
- HashFields.sln
196

207
jobs:
218
test:

‎.github/workflows/release.yml

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,11 @@ name: Publish release
22

33
on:
44
push:
5-
tags: [ "v*.*.*" ]
5+
tags:
6+
- "202[2-9].0[1-9].[1-9]" # 2022.02.2
7+
- "202[2-9].0[1-9].[1-9][0-9]" # 2022.02.22
8+
- "202[2-9].1[0-2].[1-9]" # 2022.11.1
9+
- "202[2-9].1[0-2].[1-9][0-9]" # 2022.11.11
610

711
jobs:
812
package:

‎README.md

Lines changed: 123 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,24 +4,124 @@ Selectively hash, drop, or keep fields from a flat file (e.g. CSV).
44

55
Cross-platform command-line tool built using [.NET Core 5.0](https://dotnet.microsoft.com/)
66

7-
## Getting started
7+
## Example
8+
9+
Given this input CSV file:
10+
11+
```csv
12+
column1,column2,column3,column4
13+
r1c1,r1c2,r1c3,r1c4
14+
r2c1,r2c2,r2c3,r2c4
15+
r3c1,r3c2,r3c3,r3c4
16+
r4c1,r4c2,r4c3,r4c4
17+
```
18+
19+
And this configuration:
20+
21+
* `SHA256` hash algorithm
22+
* drop `column1`, `column3`
23+
* skip `column2`
24+
* output hashed strings in lowercase and remove hyphens
25+
26+
`hashfields` produces this CSV file:
27+
28+
```csv
29+
column2,column4
30+
r1c2,fb66e41761a74ea0c042e1c226c04fa2ce1a1334d7063d86230d17f33f109b68
31+
r2c2,6051c006caee661a6ccb390b8cf7a43230c5cd7b54861f7306a598b612f924b9
32+
r3c2,7e32c53b7729f5dce7ac54232b7f2d93d6c78ed19fc8d096b0fde948f513e9dc
33+
r4c2,f8d0624d128daf97c61ec28f4396e8f14be2ca2940d18fdf33e939cda9bd1824
34+
```
35+
36+
## Usage
37+
38+
### Get the executable
39+
40+
`hashfields` is a command-line executable program. Get the latest release for
41+
your platform:
42+
43+
#### Download a pre-built binary
44+
45+
From the [Releases page](https://github.com/cal-itp/hashfields/releases)
46+
47+
#### Build from source
48+
49+
Clone and build from the `main` branch:
50+
51+
```bash
52+
git clone https://github.com/cal-itp/hashfields
53+
cd hashfields
54+
dotnet build
55+
dotnet publish -r <runtime> -c Release -o <output> src/Cli/hashfields.csproj
56+
```
57+
58+
* `<runtime>` is based on your platform: `linux-x64`, `osx.11.0-x64`, `win10-x64`
59+
* `<output>` is the folder to place the build artifacts and executable
60+
61+
### Configure runtime settings
62+
63+
In the same directory as the executable, create an `appsettings.json` file using
64+
[the sample][appsettings.json] as a guide.
65+
66+
A description of each of the settings (by section) follows:
67+
68+
#### `DataOptions`
69+
70+
| Setting | Default | Description |
71+
| ----------------- | -------- | ---------------------------------------------------------- |
72+
| `Delimiter` | `,` | The string delimiter used between fields of source data. |
73+
| `Drop` | `[]` | A list of column names to drop in the output. |
74+
| `HashAlgorithm` | `SHA512` | The algorithm to use when hashing column values. |
75+
| `HyphenateHashes` | `true` | If `true` hashed strings use hyphens between hexadecimal digits. If `false`, hyphens are not used. |
76+
| `LowercaseHashes` | `false` | If `true` hashed strings are output using lowercase hexadecimal digits. If `false`, uppercase hexadecimal digits. |
77+
| `Skip` | `[]` | A list of column names to skip from hashing in the output. |
78+
79+
#### `StreamOptions.Input`
80+
81+
| Setting | Default | Description |
82+
| --------| ------- | --------------------------------------------------------------------- |
83+
| `Type` | `StdIn` | The type of source to read data from. One of `File` or `StdIn`. |
84+
| `Path` | | Required for `Type: File`; the path to a readable delimited data file. |
85+
86+
#### `StreamOptions.Output`
87+
88+
| Setting | Default | Description |
89+
| --------| -------- | --------------------------------------------------------------------- |
90+
| `Type` | `StdOut` | The type of target to write data to. One of `File` or `StdOut`. |
91+
| `Path` | | Required for `Type: File`; the path to a writeable file. |
92+
93+
### Run the executable
94+
95+
**Windows Powershell:**
96+
97+
```powershell
98+
.\hashfields
99+
```
100+
101+
**Linux/macOS terminals:**
102+
103+
```bash
104+
./hashfields
105+
```
106+
107+
## Development getting started
8108

9109
* Open in VS Code
10110
* Rebuild and Reopen in Container
11-
* Review the [`appsettings.json`](https://github.com/cal-itp/hashfields/blob/main/src/Cli/appsettings.json) and [sample data](https://github.com/cal-itp/hashfields/blob/main/src/Cli/samples/data.csv) files
12-
* Set a breakpoint in [`src/Cli/Program.cs`](src/Cli/Program.cs) and hit `F5` to run in debug mode
111+
* Review the [`appsettings.json`][appsettings.json] and [sample data][data.csv] files
112+
* Set a breakpoint in [`src/Cli/Program.cs`][program.cs] and hit `F5` to run in debug mode
13113
* After the run completes, look in your local `src/Cli/sample` directory for the hashed output file
14114

15-
## Run the tests
115+
### Run the tests
16116

17117
Use the *Task Explorer* or enter the following commands:
18118

19-
### Run tests once
119+
#### Run tests once
20120

21121
* `Ctrl/Cmd+P` to bring up the Command Palette
22122
* Type `tasks: run test task` and hit `Enter`
23123

24-
### Watch/Run tests
124+
#### Watch/Run tests
25125

26126
* `Ctrl/Cmd+P` to bring up the Command Palette
27127
* Type `tasks: run task` and hit `Enter`
@@ -40,3 +140,20 @@ docker compose up --build deploy-alpine
40140
```
41141

42142
The `Cli` program's output is displayed in the terminal before the container shuts down.
143+
144+
## Make a release
145+
146+
Releases happen automatically with GitHub Actions. Push a calver version tag of
147+
the form `YYYY.0M.N` where:
148+
149+
* `YYYY` is the 4 digit year
150+
* `0M` is the 0-prefixed month, e.g. 01 for January, 10 for October
151+
* `N` is the 1-based release number for the given month, incremented with
152+
each release that year and month
153+
154+
See [`.github/workflows/release.yml`][release.yml] for more details.
155+
156+
[appsettings.json]: src/Cli/appsettings.json
157+
[data.csv]: src/Cli/samples/data.csv
158+
[program.cs]: src/Cli/Program.cs
159+
[release.yml]: .github/workflows/release.yml

0 commit comments

Comments
 (0)