Team Coding Standards (previously "Developer Hygiene")

[chartgerink]

Hi everyone 👋

I wanted to share some guidelines for how we work together on our project, which we're calling "Team Coding Standards" 😊. These are just some suggestions to help us work more smoothly and avoid common issues. I'm opening this discussion so we can refine these ideas together and figure out where they should live. I think a CONTRIBUTING.md file might be the best place (GitHub recognizes this too). Once we agree on the main points, I'm happy to make a pull request to add these to our project.

These suggestions are based on things I’ve noticed where we could improve as a team. They’re meant to be helpful tips specific to how we work together. They do not replace further norm building in the project and are aimed at providing a good starting point

---

Clear and Helpful Commit Messages

When you make a commit (a save point in our project), it's important to describe what you've changed in a way that's easy to understand. Use simple, active sentences. For example, say "Update button styles" instead of something vague like "changed styling." This helps everyone see what's been done just by looking at the commit history.

Keep Your Branch Up-to-Date

If you’re working on a feature in a separate branch, it’s a good idea to regularly pull in the latest changes from the main branch. This helps prevent conflicts later and keeps your work relevant. Also, if you’ve been working on a branch for a long time without pulling updates, let the team know why in your pull request. This way, everyone understands your reasoning.

Protecting the Main Branch

We want to make sure only high-quality code makes it into our main branch, which is what goes into production. To do this, we’ll require all changes to go through a pull request (PR). This means your code needs to be reviewed by someone else, and automated checks will be run to catch any issues before they become bigger problems.

Keep Pull Requests Small and Focused

When possible, try to keep your pull requests small and focused on one thing. This makes it easier for others to review your changes quickly and reduces the chance of missing issues. If a pull request is too big, it can take longer to review and might introduce more bugs.

Automated Testing

Before you commit your code, it’s important to write tests to make sure everything works as expected. Automated tests help keep our project stable by catching issues early. You can use GitHub Actions to run these tests automatically, so you know everything is working before you merge your changes into the main branch.

Write and Keep Up Documentation

Good documentation is key to helping everyone understand how our project works. A clear README file and other documents can save a lot of time. It’s helpful to document both public info (like how to set up the project on your computer) and private info (like how our servers are managed). This way, everyone can find the information they need.

Use GitHub Issues for Proposing Changes

Before you start working on something new, it’s a good idea to open a GitHub issue to get feedback. This can help you refine your ideas and make sure you’re on the right track. It also helps avoid doing work that might need to be redone later. Getting early feedback can save time and make sure your efforts are aligned with the team.

Write Clear GitHub Issues

When you create a GitHub issue, try to include all the information needed to understand the problem or task. If you don’t have all the details, ask questions and tag the right people. A well-written issue is half the work, making it easier for someone to jump in and help.

Communicate Clearly

Good communication is key to working well together. Before you send a message or comment, think about how others will read it. Try to make your point clear and simple. If you’re in a hurry, it’s easy to be misunderstood, so take a moment to check if your message is clear and concise. This will help others understand you better and keep things moving smoothly.

---

I hope these tips are helpful! Let’s discuss them further and decide where they should live in our project documentation. Once we’re all on the same page, I’ll make a pull request to add them.