Skip to content

docs: document NIPs and PR template usage #393

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tcheeric merged 2 commits into from
Aug 19, 2025
Merged

docs: document NIPs and PR template usage #393

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2083bd9
docs: mention PR template in guidelines
tcheeric Aug 19, 2025
90d6f98
Merge branch 'develop' into codex/update-agents.md-with-pr-quality-ga…
tcheeric Aug 19, 2025
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
15 changes: 10 additions & 5 deletions .github/workflows/pr-quality-gate.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,9 @@ jobs:
const files = await github.paginate(
github.rest.pulls.listFiles, { owner, repo, pull_number: pr.number }
);
const commits = await github.paginate(
github.rest.pulls.listCommits, { owner, repo, pull_number: pr.number }
);
const extsCode = ['.js','.ts','.tsx','.jsx','.py','.rb','.go','.rs','.java','.kt','.cs','.php','.c','.cc','.cpp','.m','.mm','.swift','.scala','.sh','.yml','.yaml','.json','.toml'];
const extsTests = ['.spec.','.test.','/tests/','/__tests__/'];
const codeTouched = files.some(f =>
Expand All @@ -42,10 +45,12 @@ jobs:
extsTests.some(tok => f.filename.includes(tok)));
// 1) Scope ≤ 300 lines (from GitHub blog checklist)
const scopeOK = totalChanged <= 300;
// 2) Title = verb + object (simple verb list heuristic)
// 2) Title and commits follow type: description (verb + object)
const title = prData.title.trim();
const verbs = ['Add','Fix','Update','Refactor','Remove','Implement','Document','Docs','Test','Build','Improve','Feat','Enable','Disable','Migrate'];
const titleOK = new RegExp(`^(${verbs.join('|')})\\b.+`).test(title);
const types = ['feat','fix','docs','refactor','test','chore','ci','build','perf','style'];
const naming = `^(${types.join('|')}):\\s+[A-Z][^\\s]*\\s+.+`;
Copy link

Copilot AI Aug 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The regex pattern [A-Z][^\s]*\s+.+ requires the description to start with a capital letter followed by a non-whitespace character and then whitespace, but this doesn't properly validate the 'verb + object' requirement. For example, 'docs: A' would pass validation but isn't a proper verb + object phrase. Consider refining the pattern to better match the intended format.

Suggested change
const naming = `^(${types.join('|')}):\\s+[A-Z][^\\s]*\\s+.+`;
const naming = `^(${types.join('|')}):\\s+[A-Z][a-z]+\\s+[a-zA-Z0-9].+`;

Copilot uses AI. Check for mistakes.
const titleOK = new RegExp(naming).test(title);
const commitsOK = commits.every(c => new RegExp(naming).test(c.commit.message.split('\\n')[0]));
// 3) Description “why now?” + links to issue
const body = (prData.body || '').trim();
const hasIssueLink = /#[0-9]+|https?:\/\/github\.com\/.+\/issues\/[0-9]+/i.test(body);
Expand Down Expand Up @@ -73,7 +78,7 @@ jobs:
`| Pass | Check |`,
`|:----:|:------|`,
row(`Scope ≤ 300 changed lines (current: ${totalChanged})`, scopeOK, scopeOK ? '' : 'Consider splitting into smaller PRs (stacking).'),
row(`Title starts with a verb + object (e.g., "Refactor auth middleware")`, titleOK),
row(`Title and commits use type: description (verb + object)`, titleOK && commitsOK),
row(`Description answers "why now?" and links an issue`, descOK, hasIssueLink ? '' : 'Add a linked issue (#123) or URL.'),
row(`Highlight breaking changes with **BREAKING** or ⚠️ BREAKING`, breakingOK, containsBreakingWord && !breakingFlagPresent ? 'Add explicit BREAKING flag.' : ''),
row(`Request specific feedback (e.g., "Concurrency strategy OK?")`, feedbackOK),
Expand All @@ -85,7 +90,7 @@ jobs:
// Determine blocking result (fail if any required check fails)
const failures = [];
if (!scopeOK) failures.push('Scope > 300 lines');
if (!titleOK) failures.push('Title not verb + object');
if (!titleOK || !commitsOK) failures.push('Naming format invalid');
if (!descOK) failures.push('Description lacks why/issue link');
if (!breakingOK) failures.push('Missing explicit BREAKING flag');
if (!feedbackOK) failures.push('No specific feedback requested');
Expand Down
97 changes: 96 additions & 1 deletion AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,97 @@
# Repo Guidelines

## NIPs

- https://github.com/nostr-protocol/nips/blob/master/01.md
- https://github.com/nostr-protocol/nips/blob/master/02.md
- https://github.com/nostr-protocol/nips/blob/master/03.md
- https://github.com/nostr-protocol/nips/blob/master/04.md
- https://github.com/nostr-protocol/nips/blob/master/05.md
- https://github.com/nostr-protocol/nips/blob/master/06.md
- https://github.com/nostr-protocol/nips/blob/master/07.md
- https://github.com/nostr-protocol/nips/blob/master/08.md
- https://github.com/nostr-protocol/nips/blob/master/09.md
- https://github.com/nostr-protocol/nips/blob/master/10.md
- https://github.com/nostr-protocol/nips/blob/master/11.md
- https://github.com/nostr-protocol/nips/blob/master/12.md
- https://github.com/nostr-protocol/nips/blob/master/13.md
- https://github.com/nostr-protocol/nips/blob/master/14.md
- https://github.com/nostr-protocol/nips/blob/master/15.md
- https://github.com/nostr-protocol/nips/blob/master/16.md
- https://github.com/nostr-protocol/nips/blob/master/17.md
- https://github.com/nostr-protocol/nips/blob/master/18.md
- https://github.com/nostr-protocol/nips/blob/master/19.md
- https://github.com/nostr-protocol/nips/blob/master/20.md
- https://github.com/nostr-protocol/nips/blob/master/21.md
- https://github.com/nostr-protocol/nips/blob/master/22.md
- https://github.com/nostr-protocol/nips/blob/master/23.md
- https://github.com/nostr-protocol/nips/blob/master/24.md
- https://github.com/nostr-protocol/nips/blob/master/25.md
- https://github.com/nostr-protocol/nips/blob/master/26.md
- https://github.com/nostr-protocol/nips/blob/master/27.md
- https://github.com/nostr-protocol/nips/blob/master/28.md
- https://github.com/nostr-protocol/nips/blob/master/29.md
- https://github.com/nostr-protocol/nips/blob/master/30.md
- https://github.com/nostr-protocol/nips/blob/master/31.md
- https://github.com/nostr-protocol/nips/blob/master/32.md
- https://github.com/nostr-protocol/nips/blob/master/33.md
- https://github.com/nostr-protocol/nips/blob/master/34.md
- https://github.com/nostr-protocol/nips/blob/master/35.md
- https://github.com/nostr-protocol/nips/blob/master/36.md
- https://github.com/nostr-protocol/nips/blob/master/37.md
- https://github.com/nostr-protocol/nips/blob/master/38.md
- https://github.com/nostr-protocol/nips/blob/master/39.md
- https://github.com/nostr-protocol/nips/blob/master/40.md
- https://github.com/nostr-protocol/nips/blob/master/42.md
- https://github.com/nostr-protocol/nips/blob/master/44.md
- https://github.com/nostr-protocol/nips/blob/master/45.md
- https://github.com/nostr-protocol/nips/blob/master/46.md
- https://github.com/nostr-protocol/nips/blob/master/47.md
- https://github.com/nostr-protocol/nips/blob/master/48.md
- https://github.com/nostr-protocol/nips/blob/master/49.md
- https://github.com/nostr-protocol/nips/blob/master/50.md
- https://github.com/nostr-protocol/nips/blob/master/51.md
- https://github.com/nostr-protocol/nips/blob/master/52.md
- https://github.com/nostr-protocol/nips/blob/master/53.md
- https://github.com/nostr-protocol/nips/blob/master/54.md
- https://github.com/nostr-protocol/nips/blob/master/55.md
- https://github.com/nostr-protocol/nips/blob/master/56.md
- https://github.com/nostr-protocol/nips/blob/master/57.md
- https://github.com/nostr-protocol/nips/blob/master/58.md
- https://github.com/nostr-protocol/nips/blob/master/59.md
- https://github.com/nostr-protocol/nips/blob/master/60.md
- https://github.com/nostr-protocol/nips/blob/master/61.md
- https://github.com/nostr-protocol/nips/blob/master/62.md
- https://github.com/nostr-protocol/nips/blob/master/64.md
- https://github.com/nostr-protocol/nips/blob/master/65.md
- https://github.com/nostr-protocol/nips/blob/master/66.md
- https://github.com/nostr-protocol/nips/blob/master/68.md
- https://github.com/nostr-protocol/nips/blob/master/69.md
- https://github.com/nostr-protocol/nips/blob/master/70.md
- https://github.com/nostr-protocol/nips/blob/master/71.md
- https://github.com/nostr-protocol/nips/blob/master/72.md
- https://github.com/nostr-protocol/nips/blob/master/73.md
- https://github.com/nostr-protocol/nips/blob/master/75.md
- https://github.com/nostr-protocol/nips/blob/master/77.md
- https://github.com/nostr-protocol/nips/blob/master/78.md
- https://github.com/nostr-protocol/nips/blob/master/7D.md
- https://github.com/nostr-protocol/nips/blob/master/84.md
- https://github.com/nostr-protocol/nips/blob/master/86.md
- https://github.com/nostr-protocol/nips/blob/master/87.md
- https://github.com/nostr-protocol/nips/blob/master/88.md
- https://github.com/nostr-protocol/nips/blob/master/89.md
- https://github.com/nostr-protocol/nips/blob/master/90.md
- https://github.com/nostr-protocol/nips/blob/master/92.md
- https://github.com/nostr-protocol/nips/blob/master/94.md
- https://github.com/nostr-protocol/nips/blob/master/96.md
- https://github.com/nostr-protocol/nips/blob/master/98.md
- https://github.com/nostr-protocol/nips/blob/master/99.md
- https://github.com/nostr-protocol/nips/blob/master/A0.md
- https://github.com/nostr-protocol/nips/blob/master/B0.md
- https://github.com/nostr-protocol/nips/blob/master/B7.md
- https://github.com/nostr-protocol/nips/blob/master/C0.md
- https://github.com/nostr-protocol/nips/blob/master/C7.md

## Description
nostr-java is a java implementation of the nostr protocol. The specification is available on github, here: https://github.com/nostr-protocol/nips
The URL format for the NIPs is https://github.com/nostr-protocol/nips/blob/master/XX.md where XX is the NIP number. For example, the specification for NIP-01 is available at the URL https://github.com/nostr-protocol/nips/blob/master/01.md etc.
Expand All @@ -23,14 +115,17 @@ The URL format for the NIPs is https://github.com/nostr-protocol/nips/blob/maste

## Pull Requests

- Use the pull request template at `.github/pull_request_template.md` and fill out all sections.
- Summarize the changes made and describe how they were tested.
- Include any limitations or known issues in the description.
- Add a "Network Access" section summarizing blocked domains if network requests were denied.
- Ensure all new features, modules, or dependencies are properly documented in the `README.md` file.
## PR Quality Gate

- PR summaries must reference modified files with file path citations (e.g. `F:path/to/file.java†L1-L2`).
- PR titles and commit messages must follow the `type: description` naming format (e.g., `docs: update AGENTS`).
- PR titles and commit messages must follow the `type: description` naming format.
Copy link

Copilot AI Aug 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This line duplicates the formatting requirements already specified in lines 127-128. Consider removing this line to avoid redundancy and maintain consistency with the detailed specification below.

Suggested change
- PR titles and commit messages must follow the `type: description` naming format.

Copilot uses AI. Check for mistakes.
- Allowed types: feat, fix, docs, refactor, test, chore, ci, build, perf, style.
- The description should be a concise verb + object phrase (e.g., `refactor: Refactor auth middleware to async`).
- Include a Testing section listing the commands run. Prefix each command with ✅, ⚠️, or ❌ and cite relevant terminal output.
- If network requests fail, add a Network Access section noting blocked domains.
- When TODOs or placeholders remain, include a Notes section.
Expand Down
16 changes: 16 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# Contributing to nostr-java

nostr-java implements the Nostr protocol. A complete index of current Nostr Implementation Possibilities (NIPs) is listed in [AGENTS.md](AGENTS.md).

## Development Guidelines

- Run `mvn -q verify` from the repository root before committing.
- Use `rg` for code searches instead of `ls -R` or `grep -R`.
- PR titles and commit messages must follow the `type: description` format.
- Allowed types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `ci`, `build`, `perf`, `style`.
- The description must be a concise verb + object phrase (e.g., `refactor: Refactor auth middleware to async`).
- Summaries in pull requests must cite file paths and include testing output.
- Open pull requests using the template at `.github/pull_request_template.md` and complete every section.

By following these conventions, contributors help keep the codebase maintainable and aligned with the Nostr specifications.

Loading