estimetry 0.3.0 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,11 @@ All notable changes to estimetry. Versions follow [semantic versioning](https://
|
|
|
4
4
|
|
|
5
5
|
## Unreleased
|
|
6
6
|
|
|
7
|
+
## 0.3.1 — 2026-11-22
|
|
8
|
+
|
|
9
|
+
- `emt calibrate` names the calibration settings in force on its second line, and says when they are the defaults: `Settings: calibration.minTasks 1, calibration.shrink 2 (the defaults); see emt help calibrate.` The first line and `--json` stay as they were.
|
|
10
|
+
- `emt --help` and `emt help calibrate` name the data directory as estimetry finds it: `$ESTIMETRY_HOME`, else `$XDG_DATA_HOME/estimetry`, else `~/.local/share/estimetry`; the help of calibrate takes the defaults from the calibration itself.
|
|
11
|
+
|
|
7
12
|
## 0.3.0 — 2026-11-22
|
|
8
13
|
|
|
9
14
|
- **Calibration from the first closed task.** The coefficient an estimate applies is the median of fact over estimate shrunk towards 1 with the weight n / (n + k) (`calibration.shrink`, 2 by default), instead of nothing until a slice has 5 tasks. The slices form a chain — all your tasks, the technology of the query with the most tasks, the task type — each shrunk towards the one above by the tasks no deeper slice holds, so every task counts once; the deepest applies, and the overall slice now counts too. `emt calibrate` names the slice, the number of tasks and the weight.
|
package/README.md
CHANGED
|
@@ -91,7 +91,7 @@ Codex has no personal settings inside a project, so the hooks of a personal inst
|
|
|
91
91
|
|
|
92
92
|
With `--track-commits` a `post-commit` hook is installed into the repository's hooks directory. This respects `core.hooksPath`, worktrees and husky (`.husky/post-commit`). An existing hook keeps its content: estimetry adds its own block between `# >>> estimetry >>>` and `# <<< estimetry <<<`. The hook runs estimetry in the background, so commits never wait for it. Colleagues without estimetry see nothing. A personal hook (in `.git`, or a hooks directory outside the repository) runs this installation by its paths, like the Claude Code hooks, so a commit from an IDE started from the Dock is recorded too. A hook the project commits (husky, `core.hooksPath` inside the repository) holds no paths of your machine and needs `estimetry` on `PATH`.
|
|
93
93
|
|
|
94
|
-
No task data ever goes into the repository. Tasks, estimates and the event journal live in `~/.local/share/estimetry
|
|
94
|
+
No task data ever goes into the repository. Tasks, estimates and the event journal live in `ESTIMETRY_HOME` if set, else in `$XDG_DATA_HOME/estimetry/`, else in `~/.local/share/estimetry/`; the paths below name the last.
|
|
95
95
|
|
|
96
96
|
### Flags
|
|
97
97
|
|
|
@@ -330,7 +330,7 @@ Every slice has a weight, n / (n + k), next to its median and mean (see [Estimat
|
|
|
330
330
|
}
|
|
331
331
|
```
|
|
332
332
|
|
|
333
|
-
**Settings.** Two settings in `~/.local/share/estimetry
|
|
333
|
+
**Settings.** Two settings in `config.yaml` of the data directory (`~/.local/share/estimetry/`, see [Setting up a project](#setting-up-a-project-estimetry-init) for `ESTIMETRY_HOME` and `XDG_DATA_HOME`) decide how soon calibration starts and how strongly it acts:
|
|
334
334
|
|
|
335
335
|
```yaml
|
|
336
336
|
calibration:
|
|
@@ -356,6 +356,8 @@ Setting `minTasks` without `shrink` means `shrink: 0`: a threshold you chose you
|
|
|
356
356
|
- With tasks of several types and technologies the coefficient comes from the chain of slices: the tasks of the type weigh by their number, your other tasks fill in the rest of the weight, and what is still missing stays at 1.
|
|
357
357
|
- `minTasks: 5` gives the coefficient of earlier versions wherever they gave one, with two differences. When neither the type nor a technology has 5 tasks, the median of all your tasks applies, where earlier versions gave none. The pessimistic hours are multiplied by the pessimistic coefficient, not by the coefficient, so they keep a reserve earlier versions did not give.
|
|
358
358
|
|
|
359
|
+
**Seeing them.** The second line of `emt calibrate` names the settings in force, and says when they are the defaults: `Settings: calibration.minTasks 1, calibration.shrink 2 (the defaults); see emt help calibrate.` `emt calibrate --json` has them as `minTasks` and `shrink`.
|
|
360
|
+
|
|
359
361
|
**Changing them.** Edit `config.yaml` and run `emt calibrate --type <type> --stack <a,b>`: it computes from your cards at once and names the coefficient, the slice, the number of tasks and the weight. Estimates already saved keep their coefficient. `calibration.json` follows at the next closing or with `emt rebuild`, which also rewrites a `calibration.json` of an earlier schema.
|
|
360
362
|
|
|
361
363
|
Tasks in parallel mode count with their sequential equivalent. Abandoned tasks and tasks with manual time only are left out.
|
|
@@ -1,12 +1,19 @@
|
|
|
1
|
+
import { CalibrationPolicy } from '../../../domain/calibration/calibration-policy.js';
|
|
1
2
|
import { presenterFor } from '../cli-context.js';
|
|
2
3
|
import { parseLabels } from '../parse-input.js';
|
|
3
|
-
|
|
4
|
+
const { minTasks, shrink } = CalibrationPolicy.DEFAULT;
|
|
5
|
+
/**
|
|
6
|
+
* The settings `emt calibrate` follows: help names them with the defaults of
|
|
7
|
+
* the policy, the README shows what to expect from each. The data directory is
|
|
8
|
+
* resolved as `StorageLayout.resolve` does.
|
|
9
|
+
*/
|
|
4
10
|
const SETTINGS_HELP = `
|
|
5
|
-
Settings
|
|
11
|
+
Settings, in config.yaml of the data directory ($ESTIMETRY_HOME, else
|
|
12
|
+
$XDG_DATA_HOME/estimetry, else ~/.local/share/estimetry):
|
|
6
13
|
calibration.minTasks a slice counts from this many closed tasks; with fewer
|
|
7
|
-
in all your tasks there is no coefficient (default
|
|
14
|
+
in all your tasks there is no coefficient (default ${minTasks})
|
|
8
15
|
calibration.shrink k in the weight n / (n + k) of a slice: larger is more
|
|
9
|
-
cautious, 0 applies the median as it is (default
|
|
16
|
+
cautious, 0 applies the median as it is (default ${shrink})
|
|
10
17
|
minTasks set without shrink means shrink: 0; minTasks: 5 alone gives the
|
|
11
18
|
coefficients of 0.2. Change them and run calibrate again: it recomputes from
|
|
12
19
|
your cards at once. The README shows what to expect from each setting.`;
|
|
@@ -106,8 +106,8 @@ export function formatHelp(command, helper) {
|
|
|
106
106
|
if (root) {
|
|
107
107
|
out.push('Options:', ...helper.visibleOptions(command).map((option) => row(` ${optionTerm(option)}`, optionText(option))));
|
|
108
108
|
out.push(` Most commands print JSON with --json.`);
|
|
109
|
-
out.push(` Settings: config.yaml in
|
|
110
|
-
out.push(` those of calibration: "${name} help calibrate".`, '');
|
|
109
|
+
out.push(` Settings: config.yaml in $ESTIMETRY_HOME, else $XDG_DATA_HOME/estimetry,`);
|
|
110
|
+
out.push(` else ~/.local/share/estimetry; those of calibration: "${name} help calibrate".`, '');
|
|
111
111
|
out.push('Examples:', ...EXAMPLES.map((example) => ` ${example.split(' && ').map((part) => `${name} ${part}`).join(' && ')}`), '');
|
|
112
112
|
out.push(`Run "${name} <command> --help" for details, e.g. "${name} help task new".`);
|
|
113
113
|
}
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { CalibrationPolicy } from '../../../../domain/calibration/calibration-policy.js';
|
|
1
2
|
import { formatMinutes, percent, table } from './format.js';
|
|
2
3
|
export function similarText(view) {
|
|
3
4
|
const query = [
|
|
@@ -71,7 +72,7 @@ function queried(slices) {
|
|
|
71
72
|
}
|
|
72
73
|
export function calibrationText(view) {
|
|
73
74
|
const slices = queried(view.ratio);
|
|
74
|
-
const lines = [coefficientLine(view)];
|
|
75
|
+
const lines = [coefficientLine(view), settingsLine(view)];
|
|
75
76
|
lines.push('', 'Fact over the first estimate:');
|
|
76
77
|
const ratioRows = [
|
|
77
78
|
['overall', statsText(view.ratio.overall)],
|
|
@@ -134,6 +135,12 @@ function coefficientLine(view) {
|
|
|
134
135
|
}
|
|
135
136
|
return `Without calibration: ${overall.n} of ${view.minTasks} tasks needed (calibration.minTasks).`;
|
|
136
137
|
}
|
|
138
|
+
/** The calibration settings in force, with or without a coefficient; `emt help calibrate` describes them. */
|
|
139
|
+
function settingsLine(view) {
|
|
140
|
+
const defaults = view.minTasks === CalibrationPolicy.DEFAULT.minTasks && view.shrink === CalibrationPolicy.DEFAULT.shrink;
|
|
141
|
+
const mark = defaults ? ' (the defaults)' : '';
|
|
142
|
+
return `Settings: calibration.minTasks ${view.minTasks}, calibration.shrink ${view.shrink}${mark}; see emt help calibrate.`;
|
|
143
|
+
}
|
|
137
144
|
/** A coefficient in text: two decimals are enough to read; `--json` keeps three. */
|
|
138
145
|
function times(value) {
|
|
139
146
|
return `×${Math.round(value * 100) / 100}`;
|