JavaScript Coding Guidelines for Social Changelog

This skill provides coding standards and conventions for the humanwhocodes/social-changelog project, a JavaScript utility that summarizes GitHub release changelogs into social media posts.

Code Style Requirements

Indentation

Naming Conventions

String Formatting

Function Style

- ✅ Correct: `x => x + x`, `(x, y) => x + y`, `<T>(x: T, y: T) => x === y`

- ❌ Wrong: `(x) => x + x`

Control Flow

Whitespace and Formatting

Example:

```javascript

for (let i = 0, n = str.length; i < 10; i++) {

if (x < 10) {

foo();

}

}

function f(x: number, y: string): void { }

```

Comments

Project Structure

Directory Organization

- `src/types.ts` - TypeScript type definitions

- Test files named `<source-file>.test.js`

- `tests/fixtures/` - Test data files (e.g., prompt files)

Coding Approach

Asynchronous Code

CLI Development

Console Usage

Documentation and Testing

Development Commands

```bash

Run all tests

npm test

Run individual test file

npx mocha tests/<test-file>.test.js

Run linter

npm run lint

Format code

npm run fmt

```

OpenAI API Integration

This project uses the OpenAI Responses API.

Example CURL Request

```bash

curl https://api.openai.com/v1/responses \

-H "Content-Type: application/json" \

-H "Authorization: Bearer $OPENAI_API_KEY" \

-d '{

"model": "gpt-4o-mini",

"instructions": "You are a mom of a three-year-old girl.",

"input": "Tell me a three sentence bedtime story about a unicorn.",

"previous_response_id": "resp_123456abcdef"

}'

```

**Note:** Only use `previous_response_id` when retrying a request.

Example Response Structure

The API returns a JSON object with:

Implementation Steps

When contributing to this project:

1. **Review existing code** to understand current patterns and structure

2. **Write or update tests** for any new functionality (especially CLI flags)

3. **Follow naming conventions** (PascalCase for types, camelCase for functions/variables)

4. **Use tabs for indentation** and double quotes for strings

5. **Add JSDoc comments** for public functions, interfaces, enums, and classes

6. **Handle async operations** with async/await and Promise.all

7. **Update README** with any new CLI options or usage changes

8. **Run linter and formatter** before committing (`npm run lint`, `npm run fmt`)

9. **Run tests** to ensure nothing breaks (`npm test`)

10. **Keep console usage** restricted to `cli.js` only

Constraints