Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions .github/ISSUE_TEMPLATE/bug.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
name: Report a bug
description: Describe the operation, expected behavior, and actual result.
type: Bug
body:
- type: textarea
id: behavior
attributes:
label: What happened?
description: Describe what you were trying to do, what you expected, and what actually happened.
validations:
required: true
- type: textarea
id: reproduce
attributes:
label: How can we reproduce it?
description: Provide the shortest steps or a public minimal example. If it is intermittent, describe the conditions you observed.
validations:
required: true
- type: textarea
id: environment
attributes:
label: Versions and environment
description: Include the client or peer, extension versions, deployment method, operating system, and browser as relevant. Say when a version is unknown.
validations:
required: true
- type: textarea
id: evidence
attributes:
label: Logs or screenshots
description: Optional. Remove tokens, JWT secrets, connection files, and personal data. Use private reporting for vulnerability details.
11 changes: 11 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
blank_issues_enabled: true
contact_links:
- name: Usage, deployment, and extension development questions
url: https://github.com/orgs/InKCre/discussions/categories/q-a
about: Ask a question or get help finding the responsible repository.
- name: Ideas and direction
url: https://github.com/orgs/InKCre/discussions/categories/ideas
about: Discuss suggestions that do not yet have a defined task scope.
- name: Report a security vulnerability privately
url: https://github.com/InKCre/impl-py/security/policy
about: Find the private reporting channel. Do not disclose vulnerabilities or credentials in public issues.
23 changes: 23 additions & 0 deletions .github/ISSUE_TEMPLATE/work-proposal.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
name: Propose a task
description: Propose a feature, improvement, or documentation task with an observable outcome.
type: Task
body:
- type: textarea
id: outcome
attributes:
label: What problem should this solve?
description: Who encounters the problem, under what conditions, and what should they be able to do afterward?
validations:
required: true
- type: textarea
id: scope
attributes:
label: Known scope and related material
description: Link relevant pages, repositories, extensions, existing behavior, or discussions. Include what is still uncertain.
- type: textarea
id: acceptance
attributes:
label: How would we know it is done?
description: Describe observable results, examples, or acceptance checks. An implementation design is not required.
validations:
required: true
14 changes: 14 additions & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,20 @@ https://github.com/InKCre/.github/blob/main/CONTRIBUTING.md

Related issue or task:

<!-- Use type(scope): summary for the PR title; the repository guide owns stable scopes. -->

Primary implementation scope:

Affected release projects (or `none`):

## Next action

Feedback or acceptance needed:

Person or team responding next:

Outstanding delivery and blockers (link the tracking issue for cross-repository work):

## Evidence

- [ ] I ran the repository-local required checks.
Expand Down
62 changes: 55 additions & 7 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,20 +8,52 @@ Repository-local guides own implementation, verification, and release details
for the code or documentation being changed. They extend the organization
policy and must not weaken it silently.

See [Get involved](SUPPORT.md) for questions, bug reports, contribution opportunities, and sharing your work.

## Workflow

1. For independent work, start from the latest `main` and create a focused
1. Choose an issue whose owner, outcome, and verification boundary are clear. If no suitable
`good first issue` or `help wanted` task exists, open a proposal in the owning repository before
implementing a large change.
2. For independent work, start from the latest `main` and create a focused
branch. For a dependent pull request, branch from its immediate parent and
follow the [stacked pull-request procedure](https://github.com/InKCre/.github/blob/main/GOVERNANCE.md#stacked-pull-requests).
2. Read the repository-local instructions and run its required checks.
3. Open a pull request; a draft is useful when feedback is needed early.
4. Describe intent, evidence, risk, rollback, delivery effects, and any pull
requests in the same stack.
5. Update the branch when `main` moves, wait for required checks, and resolve all
3. Read the repository-local instructions, satisfy its setup and package-access prerequisites, and
run the checks that observe the changed behavior.
4. Open a pull request; a draft is useful when feedback is needed early.
5. Describe intent, affected release projects, evidence, risk, rollback, delivery effects, and any
pull requests in the same stack.
6. Update the branch when `main` moves, wait for required checks, and resolve all
review conversations.
6. Merge with squash by default. Use rebase merge only for an intentionally
7. Merge with squash by default. Use rebase merge only for an intentionally
curated commit series.

## Change names and release projects

Use `type(scope): summary` for commit subjects and pull-request titles, with `feat`, `fix`, `ref`,
`docs`, or `chore` as the type. The title becomes the main commit subject after the default squash
merge, so write it for repository history rather than the temporary branch. Use the repository
guide's stable project or implementation area as `scope`, for example `core`, `cli`, `client-web`,
`client-webext`, or an Extension ID. For a coherent change that
crosses several projects, use an umbrella such as `extensions` or `release`; do not pack every project
name into the title.

The scope routes readers but does not select versions. List every affected release project in the
pull-request body and record user-useful release intent through that repository's Towncrier fragment,
Changeset, or equivalent mechanism. Pure contributor documentation and tooling changes do not invent
release news.

## External forks

External fork workflows require maintainer approval before read-only, secret-free CI starts. Forks
receive no preview or production credentials, so a trusted maintainer may need to run a preview after
the ordinary checks pass. Never add a credential to a branch to bypass this boundary.

Some repositories also consume packages whose read access is narrower than source access. Their
local contribution guide must name that prerequisite before the install command. A token scope alone
does not grant package access; contributors should treat `401` or `403` as an access/setup failure and
contact a maintainer instead of editing the lockfile.

Direct pushes to protected `main` are prohibited outside the audited break-glass
procedure. The initial baseline does not require an approving review, but a pull
request, repository-specific checks, and resolved conversations are still
Expand All @@ -30,3 +62,19 @@ required.
Canonical publication and production delivery happen only from protected
`main`. Pull requests may receive an isolated preview but must not receive
production credentials or publish a canonical release.

## Triage and pull-request handoff

Maintainers first confirm the problem and responsible repository, then record the next action. Use the native issue type: **Bug** for incorrect behavior, **Feature** for a new capability, or **Task** for other concrete work. The proposal form defaults to Task; adjust it after confirming scope. Ask for missing observations in a specific comment. Record issue-to-issue blockers with GitHub's native dependencies; describe external prerequisites and the condition that clears them in the issue or PR. Use GitHub's native open/closed, draft, and reviewer state.

The current board uses Project **Status** for coordination stage and Project **Priority** when prioritization is needed. These fields cover both issues and PRs; organization issue fields do not apply to PRs. Keep one source for each concept rather than also assigning status or priority labels or duplicating them in organization fields. Repository identity and the affected projects named in the issue or PR provide scope; add an area label only for a demonstrated routing or filtering need.

`help wanted` identifies work with a defined scope and acceptance criteria that welcomes external contributions. Add `good first issue` only when it also has a code or documentation starting point, needs no organization-private credentials, and names a contact willing to help. The contact and implementation assignee may differ: name the contact in the issue, then assign implementation after a contributor confirms they are taking it. Create opportunities from real work rather than placeholder tasks.

Use `documentation` where it helps contributors find documentation work. Retain labels required by dependency bots or release automation. Existing labels on historical items remain useful context, but do not copy the full legacy label set into new repositories or new work. PR titles and descriptions carry their change type; PRs do not have a native issue type.

When marking a PR ready, the author states the feedback needed, outstanding acceptance or delivery work, and the person or team responsible for responding next. A maintainer who accepts the handoff sets the assignee and requests a capable reviewer other than the author when available. With one available maintainer, record the manual review and acceptance conclusion publicly. Existing Governance still owns branch protection; this workflow adds neither self-approval nor an implicit approval requirement.

For cross-repository work, one tracking issue links the PRs and records version, acceptance, and publication dependencies. Each PR retains its own scope and evidence. Small fixes can go directly to a PR. After merging, retain outstanding publication, consumer migration, or acceptance work in the tracking issue until the promised delivery is complete.

The [current collaboration board](https://github.com/orgs/InKCre/projects/12) shows work admitted for coordination. **Triage** needs scope or ownership confirmation; **Ready to pick up** meets the handoff conditions; **In progress** is being implemented; **Review / acceptance** awaits feedback, behavior evidence, merging, or a publication decision; **Done** means the task's promised delivery is complete. Update related items when handling issues, PRs, and releases. Passing CI alone does not complete delivery, and age alone does not close an issue. Historical boards retain their records and point to the current entry. Maintainers respond as availability allows; the project does not promise a fixed response time.
22 changes: 22 additions & 0 deletions SUPPORT.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# Get involved with InKCre

Ask questions about using, deploying, or extending InKCre in [Q&A](https://github.com/orgs/InKCre/discussions/categories/q-a). Discuss ideas and direction in [Ideas](https://github.com/orgs/InKCre/discussions/categories/ideas). If you do not know which repository owns a problem, describe your goal, what you tried, and what blocked you; maintainers can help route it.

Report a concrete bug or propose a defined task in its implementation repository:

| Area | Repository |
| --------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Python peer, database contract, CLI, Python extensions | [impl-py](https://github.com/InKCre/impl-py/issues/new/choose) |
| Web app, browser extension, TS SDK, Web extension distributions | [impl-ts](https://github.com/InKCre/impl-ts/issues/new/choose) |
| macOS / Swift peer | [impl-swift](https://github.com/InKCre/impl-swift/issues/new/choose) |
| UI components and design system | [ui](https://github.com/InKCre/ui/issues/new/choose) |
| User manual and developer guides | [docs](https://github.com/InKCre/docs/issues/new/choose) |
| Extension Registry and Toolkit | [ext-reg](https://github.com/InKCre/ext-reg/issues/new/choose) |
| Agent skills | [agent-skills](https://github.com/InKCre/agent-skills/issues/new/choose) |
| Cross-repository collaboration and contribution workflow | [.github](https://github.com/InKCre/.github/issues/new/choose) |

Include expected and actual behavior, versions, and the shortest reproduction you can provide. Remove tokens, JWT secrets, connection files, and personal information from logs and screenshots. Report security vulnerabilities through the affected repository's private channel; if no channel exists or ownership is unclear, use the fallback in the [security policy](https://github.com/InKCre/impl-py/security/policy).

To contribute code or documentation, browse [help wanted](https://github.com/issues?q=org%3AInKCre+is%3Aissue+is%3Aopen+label%3A%22help+wanted%22), [good first issue](https://github.com/issues?q=org%3AInKCre+is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22), and the [current collaboration board](https://github.com/orgs/InKCre/projects/12). Comment on a task to confirm scope and a contact before starting, then follow [Contributing](CONTRIBUTING.md). You can propose work or ask for guidance without submitting code first.

Share extensions, workflows, and experiences in [Show and tell](https://github.com/orgs/InKCre/discussions/categories/show-and-tell). Release and compatibility announcements belong in [Announcements](https://github.com/orgs/InKCre/discussions/categories/announcements).
6 changes: 4 additions & 2 deletions profile/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ InKCre is an open-source, self-hostable system for **collecting, organizing, and

[Website](https://inkcre.dev) · [Developer Guide](https://inkcre.dev/developer/) · [Architecture](https://inkcre.dev/developer/architecture)

[Discussions](https://github.com/orgs/InKCre/discussions) · [Get involved](https://github.com/InKCre/.github/blob/main/SUPPORT.md) · [Current work](https://github.com/orgs/InKCre/projects/12)

## The idea

Information is scattered across messages, feeds, documents, and apps. Capturing it is only the first step — the harder problem is making it remain useful after its original context has passed.
Expand Down Expand Up @@ -47,6 +49,6 @@ InKCre is a multi-repository project under active development.

## Why "InKCre"?

**In · K · Cre** = **In**formation → **K**nowledge → **Cre**ation, and sounds like *increase*.
**In · K · Cre** = **In**formation → **K**nowledge → **Cre**ation, and sounds like _increase_.

Also known in Chinese as **第三持存** — *tertiary retention*.
Also known in Chinese as **第三持存** — _tertiary retention_.