Guide · Open source

How to use project-guidelines: a JavaScript team standard

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

project-guidelines is a collection of best-practice notes for maintaining JavaScript projects, written and gathered by the elsewhen team. It is a reading resource, not software you install, so 'using' it means reading it and deciding which rules your team should adopt. This guide shows how to read it locally, what its Git rules say, and how to adapt it for your own team.

Project Guidelineselsewhencode/project-guidelines · ★ 29.4k · MIT Install options & downloads

Quick start

1Clone or open the repository. Clone the repository with the git clone command from the README, or open it on GitHub to read online.
2Read the Git section first. Start with the Git rules and workflow, since they are the most concrete part of the document.
3Pick the rules your team will follow. Go through each section and mark which guidelines to keep, change or drop.
4Write the agreed rules down. Record your chosen branching and commit rules in your own project documentation so everyone sees the same standard.
5Apply the rules in your next Pull Request. Create a feature branch, commit with the agreed message style, rebase, and open a Pull Request.

What project-guidelines is and who it is for

The README describes the guidelines as a list the elsewhen team has found and written that, in their view, works well with most JavaScript projects. The document covers Git branching and commit messages, documentation, environments, dependencies, testing, code style, logging, API design and accessibility.

It suits teams that want a shared written standard for Git branching and pull requests, developers new to collaborative JavaScript projects who want a starting checklist, and maintainers who want a reference to discuss and adapt. It is not a tool or library, and the README focuses on principles rather than configuration.

Read project-guidelines locally

You can read the guidelines online in the repository, or clone it to read it on your machine. The README gives this command for cloning the repository.

git clone https://github.com/elsewhencode/project-guidelines

Adopt the core Git rules

The Git section sets out a feature-branch approach. Work happens on a dedicated branch branched out from develop, changes reach develop and master through Pull Requests, and feature branches are deleted after merging. The README also asks you to make sure your branch builds and passes tests, including code style checks, before opening a Pull Request.

The Git workflow section describes the main steps: create a feature branch, commit small coherent changes, sync with develop, rebase interactively, push, open a Pull Request, then clean up the local branch. Rebasing changes history, so the README says to use -f to force the push, or the less destructive --force-with-lease if someone else works on the branch.

Perform work in a feature branch and never push directly into develop or master.
Update develop and do an interactive rebase before pushing and opening a Pull Request.
Resolve conflicts while rebasing, before making the Pull Request.
Delete local and remote feature branches after merging.
Use the provided .gitignore file and protect the develop and master branches.

git checkout -b <branchname>
git checkout develop
git pull
git checkout <branchname>
git rebase -i --autosquash develop
git push -f

Write commit messages the way the guide suggests

The commit section gives rules of thumb drawn from a commonly cited set of commit guidelines. Separate the subject from the body with a blank line, keep the subject to 50 characters, wrap the body at 72, capitalise the subject, do not end it with a period, and use the imperative mood.

Separate subject and body with a newline.
Limit the subject line to 50 characters and wrap the body at 72.
Capitalise the subject line and do not end it with a period.
Use the imperative mood in the subject line.

Adapt the guidelines for your team

Because the document is a set of principles, the practical step is to decide which rules you will keep. The README itself invites people to share a best practice or suggest removing one by contributing to the project. Note that the README says the develop branch approach may be overkill for some projects.

If your team already has established conventions and needs specific tooling setup, this document will not provide it. Use it as a discussion starter, then write your chosen rules into your own contributing notes.

What people use it for

A team agreeing on a feature-branch and Pull Request process before starting a new JavaScript project.
A new developer joining a collaborative project who wants a checklist for Git and commits.
A maintainer preparing a discussion document on which team conventions to adopt.
A team reviewing its existing Git habits against the rebase and force-push guidance.

Frequently asked questions

Is project-guidelines a tool I can install?

No. The README describes it as a set of best-practice guidelines, and the listed install method is read-online. It is a document you read and adapt, not software you install.

Do I need any prerequisites to use it?

The source lists no prerequisites. To read the guidelines locally you can clone the repository with git clone, which requires Git.

Is project-guidelines free to use?

The repository is licensed under MIT. Check the LICENSE file in the repository for the full terms.

What is the difference between project-guidelines and Conventional Commits?

project-guidelines covers many areas of JavaScript project work, including Git, testing, logging and accessibility. Conventional Commits focuses on a specific commit message format, so the two address different scopes.

Should I use this instead of the Airbnb or Google JavaScript style guides?

Those are style guides for writing code, while project-guidelines is a broader set of team practices. Teams often read a style guide for code formatting alongside this document for workflow.

Why does the guide say to use force push after rebasing?

Rebasing changes the history of your feature branch, so Git rejects a normal push. The README says to use -f, or --force-with-lease if someone else is working on the branch.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use project-guidelines if your team wants a written starting standard for Git branching, pull requests and general JavaScript project practice that you can discuss and adapt. Pick something else if you need an installable tool, a linter setup, or configuration specific to your existing conventions.

Install options & downloads