Skip to content

Commit ce8c576

Browse files
Copilottobiasdiez
Copilot
and
tobiasdiez
authored
chore: create GitHub Copilot instructions (#2787)
- [x] Create comprehensive GitHub Copilot instructions with validated commands and timing - [x] Update instructions to reflect automated PostgreSQL and Redis setup in Copilot environment - [x] Remove all local development references and focus exclusively on automated Copilot environment - [x] Update database credentials and Redis port mapping - [x] Add environment setup section for automated configuration only - [x] Add debugging and development workflow section with VS Code configurations - [x] Enhance database schema development workflow with prototyping and migration steps - [x] Add GraphQL development guidance - [x] Improve troubleshooting with code generation and hot reload issues - [x] Clarify automated environment setup with specific URLs and credentials <!-- START COPILOT CODING AGENT TIPS --> --- 💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more [Copilot coding agent tips](https://gh.io/copilot-coding-agent-tips) in the docs. --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: tobiasdiez <[email protected]> Co-authored-by: Tobias Diez <[email protected]> Co-authored-by: Tobias Diez <[email protected]>
1 parent d7baa96 commit ce8c576

File tree

3 files changed

+218
-2
lines changed

3 files changed

+218
-2
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# JabRefOnline Development Instructions
2+
3+
JabRefOnline is a modern Nuxt.js web application serving as the homepage for JabRef (https://www.jabref.org/). It's built with Vue.js, TypeScript, GraphQL, Prisma, PostgreSQL, and Redis, featuring a complete full-stack architecture with database management, authentication, and content management.
4+
5+
**Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.**
6+
7+
## Working Effectively
8+
9+
### Initial Setup
10+
11+
PostgreSQL and Redis services are automatically provided with pre-configured environment variables in the Copilot environment. The database is already created and seeded.
12+
The dependencies are already installed.
13+
14+
### Build and Development Commands
15+
16+
**CRITICAL - Build Timeouts:**
17+
18+
- **NEVER CANCEL** build commands. Set timeout to 120+ minutes.
19+
- Build takes 45-60 seconds normally but can take longer on first run.
20+
- Always wait for builds to complete fully.
21+
22+
```bash
23+
# Development server (NEVER CANCEL - takes 30+ seconds to start)
24+
pnpm dev # Runs on http://localhost:3000 - TIMEOUT: 120+ seconds
25+
26+
# Production build (NEVER CANCEL - takes 45-60 seconds)
27+
pnpm build # TIMEOUT: 120+ seconds
28+
29+
# Production server (requires build first)
30+
pnpm start # Runs on http://localhost:3000
31+
```
32+
33+
### Testing Commands
34+
35+
**CRITICAL - Test Execution:**
36+
37+
- E2E tests **REQUIRE** development server running first
38+
- Unit tests are independent and run quickly
39+
- **NEVER CANCEL** test suites. Set timeout to 60+ minutes.
40+
41+
```bash
42+
# Unit tests only (fast, independent)
43+
pnpm test:unit # Takes ~11 seconds
44+
45+
# E2E tests (REQUIRES dev server running in separate terminal)
46+
# Terminal 1: pnpm dev (keep running)
47+
# Terminal 2:
48+
export TEST_URL="http://localhost:3000"
49+
pnpm test:e2e # Takes ~13 seconds
50+
51+
# Integration tests
52+
pnpm test:integration # Takes ~15 seconds
53+
54+
# All tests (some will fail if dev server not running)
55+
pnpm test # Takes ~13 seconds - TIMEOUT: 60+ seconds
56+
```
57+
58+
### Quality Assurance Commands
59+
60+
```bash
61+
# Linting (comprehensive check)
62+
pnpm lint # Takes ~30 seconds - warnings expected, no errors
63+
64+
# Type checking
65+
pnpm typecheck # Takes ~22 seconds
66+
67+
# GraphQL validation
68+
pnpm validate # Takes ~1.5 seconds
69+
```
70+
71+
### Additional Development Tools
72+
73+
```bash
74+
# Storybook UI components (NEVER CANCEL - takes 7+ seconds to start)
75+
pnpm storybook # Runs on http://localhost:6006 - TIMEOUT: 120+ seconds
76+
77+
# Database visual editor
78+
pnpm prisma:studio # Runs on http://localhost:5555
79+
80+
# Database operations
81+
pnpm prisma:push # Push schema changes to dev DB
82+
pnpm prisma:migrate:dev # Create and apply new migration
83+
```
84+
85+
## Workflows
86+
87+
**Database Schema Development Workflow:**
88+
89+
1. **Prototyping Phase:**
90+
91+
```bash
92+
# Make changes to server/database/schema.prisma
93+
pnpm prisma:push # Push changes to database (no migration)
94+
# Iterate and test changes
95+
```
96+
97+
2. **Migration Creation:**
98+
```bash
99+
pnpm prisma:migrate:dev # Generate migration file from schema changes
100+
pnpm prisma:seed # Re-seed if needed
101+
```
102+
103+
**GraphQL Development:**
104+
105+
- Schema located at `server/schema.graphql`
106+
- Resolvers in `server/resolvers.ts`
107+
- Generated types automatically updated on file changes
108+
- GraphQL endpoint: `http://localhost:3000/api`
109+
110+
## Validation Scenarios
111+
112+
**ALWAYS manually validate changes using these complete user scenarios:**
113+
114+
### Scenario 1: Basic Homepage Functionality
115+
116+
1. Start development server: `pnpm dev`
117+
2. Navigate to http://localhost:3000
118+
3. Verify homepage loads with "Stay on top of your Literature" heading
119+
4. Test navigation: click "Features" link
120+
5. Verify page scrolls to #features section
121+
6. Check browser console for critical errors (warnings are expected)
122+
123+
### Scenario 2: Full Development Workflow
124+
125+
1. Make code changes to components or pages
126+
2. Verify that it works in the browser
127+
3. Run unit tests: `pnpm test:unit`
128+
4. Test E2E with dev server running: `pnpm test:e2e`
129+
130+
### Scenario 3: Production Build Validation
131+
132+
1. Build application: `pnpm build`
133+
2. Start production server: `pnpm start`
134+
3. Verify application loads correctly
135+
4. Test key navigation and functionality
136+
137+
## Technology Stack and Architecture
138+
139+
- **Frontend:** Nuxt.js 4, Vue.js 3, TypeScript
140+
- **Styling:** Tailwind CSS, Naive UI components
141+
- **Backend:** Nuxt server API, GraphQL with Apollo
142+
- **Database:** PostgreSQL with Prisma ORM
143+
- **Cache:** Redis for session storage
144+
- **Testing:** Vitest for unit/integration/E2E tests
145+
- **UI Development:** Storybook for component development
146+
147+
## Important Directory Structure
148+
149+
```
150+
/server/ # Backend API, GraphQL resolvers, database models
151+
/pages/ # Nuxt.js route pages
152+
/components/ # Vue.js reusable components
153+
/layouts/ # Page layout templates
154+
/content/ # Markdown content files
155+
/assets/ # Uncompiled assets (CSS, images)
156+
/public/ # Static files served directly
157+
/apollo/ # GraphQL client configuration
158+
/test/ # Test utilities and setup
159+
/.github/workflows/ # CI/CD pipeline configuration
160+
```
161+
162+
## Pre-commit Checklist
163+
164+
Before committing changes, always run:
165+
166+
1. `pnpm test:unit` - All unit tests must pass
167+
2. `pnpm build` - Must build successfully
168+
3. `pnpm lint` - Fix any errors, warnings are acceptable
169+
4. `pnpm typecheck` - Must pass without errors
170+
171+
The CI pipeline (.github/workflows/ci.yml) will fail if linting, type checking, building, or core tests fail.
172+
173+
## Development Servers and Ports
174+
175+
- **Main application:** http://localhost:3000 (dev server)
176+
- **Storybook:** http://localhost:6006 (component development)
177+
- **Prisma Studio:** http://localhost:5555 (database management)
178+
- **Tailwind Viewer:** http://localhost:3000/\_tailwind/ (CSS utility viewer)
179+
180+
Always ensure ports are available before starting services. The development server includes hot reload and will automatically reflect code changes.

‎.github/workflows/copilot-setup-steps.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,37 @@ jobs:
1717
permissions:
1818
contents: read
1919

20+
services:
21+
postgres:
22+
image: postgres@sha256:29e0bb09c8e7e7fc265ea9f4367de9622e55bae6b0b97e7cce740c2d63c2ebc0
23+
env:
24+
POSTGRES_PASSWORD: postgres
25+
POSTGRES_DB: jabref
26+
# Set health checks to wait until postgres has started
27+
options: >-
28+
--health-cmd pg_isready
29+
--health-interval 10s
30+
--health-timeout 5s
31+
--health-retries 5
32+
ports:
33+
- 5432:5432
34+
35+
redis:
36+
image: redis@sha256:cc2dfb8f5151da2684b4a09bd04b567f92d07591d91980eb3eca21df07e12760
37+
# Set health checks to wait until redis has started
38+
options: >-
39+
--health-cmd "redis-cli ping"
40+
--health-interval 10s
41+
--health-timeout 5s
42+
--health-retries 5
43+
ports:
44+
# Maps port 6379 on service container to port 6380 on host
45+
- 6380:6379
46+
47+
env:
48+
NUXT_DATABASE_URL: postgresql://postgres:postgres@localhost:5432/jabref?schema=public
49+
NUXT_SESSION_PASSWORD: somerandompasswordforcopilotNxFHaqCSPpBe6n5kRz2dru4hJ7K9bjgEtmsV8QAT3MDXcUfWGL
50+
2051
steps:
2152
- name: Checkout
2253
uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
@@ -32,3 +63,6 @@ jobs:
3263

3364
- name: Install dependencies
3465
run: pnpm install
66+
67+
- name: Init database
68+
run: pnpm prisma:push

‎.github/workflows/deploy-preview.yml‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,10 @@ jobs:
3131
# We could also add these checks to a job-wide if condition, to skip the workflow if its unsecure to run.
3232
# However, Github views skipped workflows as "successful" and thus one could merge a PR without running this workflow first.
3333
- name: Fail if unsecure
34-
if: "github.event_name != 'workflow_dispatch' && !contains(github.event.pull_request.labels.*.name, 'status: safe to test') && github.actor != 'tobiasdiez' && github.actor != 'dependabot[bot]' && github.actor != 'renovate[bot]'"
35-
run: exit 1
34+
if: "github.event_name != 'workflow_dispatch' && !contains(github.event.pull_request.labels.*.name, 'status: safe to test') && github.actor != 'tobiasdiez' && github.actor != 'dependabot[bot]' && github.actor != 'renovate[bot]' && github.actor != 'copilot-swe-agent'"
35+
run: |
36+
echo "The workflow was triggered by ${{ github.actor }} and the PR is not labeled as 'safe to test'. For security reasons, we do not run this workflow in this case."
37+
exit 1
3638
3739
- name: Checkout
3840
uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0

0 commit comments

Comments
 (0)