retentioneering-contributing

Name: retentioneering-contributing
Author: retentioneering

907stars136forks

How to install retentioneering-contributing?

retentioneering/retentioneering-tools/retentioneering-contributing

$npx -y skills add retentioneering/retentioneering-tools --skill retentioneering-contributing

Installs into the current project.

Summary

Help the user turn their Retentioneering ideas, friction reports, bug findings, or feature needs into high-quality upstream contributions: from capturing and validating the idea, through minimal reproductions and issue drafts, to preparing, testing, and submitting a pull request

Files · 1

View on GitHub

SKILL.md

1	# Contributing to retentioneering-tools
2
3	## Objective
4
5	Convert a user's observation — a bug, a paper cut, a missing capability, a workaround
6	they keep re-writing — into the smallest upstream change that would have prevented it,
7	packaged so maintainers can accept it quickly.
8
9	## Bundled references
10
11	\| File \| Read it when \|
12	\|---\|---\|
13	\| `references/repo-conventions.md` \| before touching code — build/test/docs commands, architecture rules, naming, sync obligations \|
14	\| `references/proposal-templates.md` \| when drafting — issue/feature/PR templates with worked examples \|
15
16	## The full route: idea → merged PR
17
18	### Stage 1 — Capture the observation properly (do this even for "small" ideas)
19
20	Record four things while they are fresh:
21	1. Expectation — what the user believed would happen (quote the docstring/docs page
22	that created the expectation, if any).
23	2. Reality — what actually happened (exact error text or wrong output).
24	3. Cost — time lost, wrong conclusion nearly shipped, workaround written.
25	4. Environment — `retentioneering.__version__`, Python, OS, install source
26	(pip wheel vs source checkout).
27
28	Field lesson: reports formatted as expectation/reality/cost/repro get acted on;
29	"X is broken" reports stall.
30
31	### Stage 2 — Validate against the CURRENT version
32
33	Many pain points are already fixed on `v5-migration` — verify before drafting:
34
35	1. `git log --oneline -30` and `CHANGELOG.md` — search keywords from the observation.
36	2. Search existing issues/PRs: `gh issue list --search "<keywords>"`, `gh pr list ...`.
37	3. Reproduce on the current checkout (see Stage 3). If it no longer reproduces, the
38	contribution may become a docs clarification or a regression test instead — both welcome.
39
40	### Stage 3 — Minimal reproduction (the heart of a bug report)
41
42	Build the smallest toy that shows the gap, e.g.:
43
44	```python
45	import pandas as pd
46	from retentioneering import Eventstream
47	df = pd.DataFrame({"user_id": ["u1","u1","u2"], "event": ["a","b","a"],
48	"timestamp": pd.date_range("2026-01-01", periods=3, freq="1min")})
49	# EXPECTED: ... ACTUAL: ...
50	```
51
52	Rules: synthetic data only (never the user's real log); deterministic (fixed frames, no
53	randomness without seed); one behavior per repro; assert the expectation so the repro
54	doubles as a failing test.
55
56	### Stage 4 — Choose the contribution shape
57
58	\| Situation \| Shape \|
59	\|---\|---\|
60	\| Clear defect with repro \| Issue with repro; PR with fix + regression test if user wants to go further \|
61	\| Surprising-but-documented behavior \| Docs PR (docstring is the source of truth — site pages regenerate from it) \|
62	\| Missing capability \| Feature issue: use-case first, proposed signature second, evidence third (see templates) \|
63	\| Repeated workaround in user's code \| Extract as proposed API: show the workaround, its cost, the proposed call replacing it \|
64	\| Wrong-conclusion trap (library was silent) \| Frame as "missing signal": what the library knew and did not surface; propose the warning/field \|
65
66	For API proposals, the accepted framing (from templates): problem → evidence of frequency
67	→ proposed signature → semantics incl. edge cases → acceptance criteria → migration notes.
68
69	### Stage 5 — Implement (when making a PR, not just an issue)
70
71	Read `references/repo-conventions.md` first. Non-negotiables:
72
73	1. Fork or branch from `master`-tracking `v5-migration`; one logical change per PR.
74	2. `make install-dev` — installs deps (`uv sync` + `npm install`) and wires the git hook
75	(a one-time-per-clone step) so commits are auto-checked; skip it and commits bypass the hooks
76	locally and CI's `lint` job flags the formatting on your PR. Add `make build` only when
77	touching widgets/JS.
78	3. Follow naming conventions (ADR-0008): `path_col/event_col/timestamp_col/s

People who liked this also viewed

6 picks

Type

retentioneering-contributing

907stars136forks

View on GitHub

How to install retentioneering-contributing?

retentioneering/retentioneering-tools/retentioneering-contributing

$npx -y skills add retentioneering/retentioneering-tools --skill retentioneering-contributing

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Contributing to retentioneering-tools
2
3	## Objective
4
5	Convert a user's observation — a bug, a paper cut, a missing capability, a workaround
6	they keep re-writing — into the smallest upstream change that would have prevented it,
7	packaged so maintainers can accept it quickly.
8
9	## Bundled references
10
11	\| File \| Read it when \|
12	\|---\|---\|
13	\| `references/repo-conventions.md` \| before touching code — build/test/docs commands, architecture rules, naming, sync obligations \|
14	\| `references/proposal-templates.md` \| when drafting — issue/feature/PR templates with worked examples \|
15
16	## The full route: idea → merged PR
17
18	### Stage 1 — Capture the observation properly (do this even for "small" ideas)
19
20	Record four things while they are fresh:
21	1. Expectation — what the user believed would happen (quote the docstring/docs page
22	that created the expectation, if any).
23	2. Reality — what actually happened (exact error text or wrong output).
24	3. Cost — time lost, wrong conclusion nearly shipped, workaround written.
25	4. Environment — `retentioneering.__version__`, Python, OS, install source
26	(pip wheel vs source checkout).
27
28	Field lesson: reports formatted as expectation/reality/cost/repro get acted on;
29	"X is broken" reports stall.
30
31	### Stage 2 — Validate against the CURRENT version
32
33	Many pain points are already fixed on `v5-migration` — verify before drafting:
34
35	1. `git log --oneline -30` and `CHANGELOG.md` — search keywords from the observation.
36	2. Search existing issues/PRs: `gh issue list --search "<keywords>"`, `gh pr list ...`.
37	3. Reproduce on the current checkout (see Stage 3). If it no longer reproduces, the
38	contribution may become a docs clarification or a regression test instead — both welcome.
39
40	### Stage 3 — Minimal reproduction (the heart of a bug report)
41
42	Build the smallest toy that shows the gap, e.g.:
43
44	```python
45	import pandas as pd
46	from retentioneering import Eventstream
47	df = pd.DataFrame({"user_id": ["u1","u1","u2"], "event": ["a","b","a"],
48	"timestamp": pd.date_range("2026-01-01", periods=3, freq="1min")})
49	# EXPECTED: ... ACTUAL: ...
50	```
51
52	Rules: synthetic data only (never the user's real log); deterministic (fixed frames, no
53	randomness without seed); one behavior per repro; assert the expectation so the repro
54	doubles as a failing test.
55
56	### Stage 4 — Choose the contribution shape
57
58	\| Situation \| Shape \|
59	\|---\|---\|
60	\| Clear defect with repro \| Issue with repro; PR with fix + regression test if user wants to go further \|
61	\| Surprising-but-documented behavior \| Docs PR (docstring is the source of truth — site pages regenerate from it) \|
62	\| Missing capability \| Feature issue: use-case first, proposed signature second, evidence third (see templates) \|
63	\| Repeated workaround in user's code \| Extract as proposed API: show the workaround, its cost, the proposed call replacing it \|
64	\| Wrong-conclusion trap (library was silent) \| Frame as "missing signal": what the library knew and did not surface; propose the warning/field \|
65
66	For API proposals, the accepted framing (from templates): problem → evidence of frequency
67	→ proposed signature → semantics incl. edge cases → acceptance criteria → migration notes.
68
69	### Stage 5 — Implement (when making a PR, not just an issue)
70
71	Read `references/repo-conventions.md` first. Non-negotiables:
72
73	1. Fork or branch from `master`-tracking `v5-migration`; one logical change per PR.
74	2. `make install-dev` — installs deps (`uv sync` + `npm install`) and wires the git hook
75	(a one-time-per-clone step) so commits are auto-checked; skip it and commits bypass the hooks
76	locally and CI's `lint` job flags the formatting on your PR. Add `make build` only when
77	touching widgets/JS.
78	3. Follow naming conventions (ADR-0008): `path_col/event_col/timestamp_col/s

People who liked this also viewed

6 picks

Type