diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml new file mode 100644 index 0000000..a8f7f03 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -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. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..261c2fc --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -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. diff --git a/.github/ISSUE_TEMPLATE/work-proposal.yml b/.github/ISSUE_TEMPLATE/work-proposal.yml new file mode 100644 index 0000000..8f8d732 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/work-proposal.yml @@ -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 diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 19e2df1..3645369 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -10,6 +10,20 @@ https://github.com/InKCre/.github/blob/main/CONTRIBUTING.md Related issue or task: + + +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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cbf6670..1edbe29 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 @@ -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. diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..6589591 --- /dev/null +++ b/SUPPORT.md @@ -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). diff --git a/profile/README.md b/profile/README.md index dea79cf..1e04a28 100644 --- a/profile/README.md +++ b/profile/README.md @@ -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. @@ -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_.