Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
115 lines (86 loc) · 3.21 KB

CONTRIBUTING.md

File metadata and controls

115 lines (86 loc) · 3.21 KB
Raw

Contributing to hawk-graph

Thanks for your interest in improving the hawk-eco architecture visualization platform! This guide covers the conventions used in this repo.

Quick start

  1. Fork the repo and create a feature branch off main: 
    git checkout -b feat/short-description
  2. Make your changes in small, focused commits.
  3. Run the local checks before pushing: 
    node --check server.js
bash -n scripts/*.sh
  4. Open a pull request. CI will re-run the same checks plus duplication detection.

Project structure

hawk-graph/
├── server.js              # Unified HTTP server (port 4000)
├── index.html             # Single-page dashboard
├── repos/                 # Tree + callflow HTMLs per repo (generated)
├── global/                # Global architecture D3 tree (generated)
├── scripts/               # Analysis + regeneration scripts
│   ├── serve.sh           # Start GitNexus + dashboard
│   ├── extract-all.sh     # Re-run Graphify on all repos
│   ├── analyze-all-gitnexus.sh  # Re-run GitNexus
│   └── refresh-trees.sh   # Regenerate all HTMLs
└── docs/                  # Documentation

Development

# Start the development server
./scripts/serve.sh

# Or manually:
gitnexus serve &              # required for GitNexus features
node server.js                # unified dashboard on port 4000
open http://localhost:4000

Regenerating graphs

The repos/ and global/ directories contain generated HTML files. To regenerate them:

./scripts/extract-all.sh
./scripts/analyze-all-gitnexus.sh
./scripts/refresh-trees.sh

Do not hand-edit generated files in repos/ or global/. Regenerate them with the scripts above instead.

Commit message convention

We use Conventional Commits.

<type>(<optional scope>): <short summary>

<optional body>

Types:

  • feat: — a new feature
  • fix: — a bug fix
  • perf: — performance improvement
  • refactor: — code restructure with no behaviour change
  • docs: — documentation only
  • test: — adding or fixing tests
  • build: — build system or dependencies
  • ci: — CI configuration
  • chore: — anything else
  • revert: — reverts a previous commit

Pull request checklist

Before requesting review:

  • node --check server.js passes locally.
  • bash -n scripts/*.sh passes locally.
  • No hand-edited generated files in repos/ or global/.
  • CHANGELOG.md updated if user-visible.
  • No secrets, API keys, or PII in code.

Code review etiquette

  • Reviewers focus on correctness and design.
  • Authors respond to every comment (resolved, addressed, or politely declined with rationale).
  • Squash-merge by default; the PR title becomes the commit.

Reporting bugs

Open an issue using the bug-report template. Include reproduction steps, expected behaviour, and actual behaviour.

Reporting security issues

Do not open a public issue. See SECURITY.md for private reporting channels.

License

By contributing, you agree that your contributions will be licensed under the same license as this repo (see LICENSE).