Skip to content

CONTRIB.md

Latest commit

 

History

History
111 lines (87 loc) · 4.54 KB

CONTRIB.md

File metadata and controls

111 lines (87 loc) · 4.54 KB

Solidar Developer Guide

Welcome

So you want to contribute to this project. Thanks in advance for your time and effort.

Consider getting in contact with the SomLabs community. You are very welcome to join in.

Technologies

Vite as building tool

React as UI framework

MUI as component library

Code style

Code style encoded into editorconfig and prettier configuration. Configure your editor to obey and just let them take over.

If you stil have to commit style related changes, please, separate them from actual code changes, to avoid obfuscating the later in diffs.

Code layout

Source code inside src is organized in directories by vertical (page/feature) slicing. Those directories are UpperCamelCase.

Horizontal slicing (per object type: components, hooks, services, data...) is used for shared code and they are located at top level. They use lowercase names. Horizontal slices may be also used to split huge vertical slices.

Keep one file per component and name the file like the component with jsx extension. Name test files like their SUT with .test. infix and place them in the same directory.

TODO: Naming convention for non component files.

Branching and PR's

  • Open a feature branch
  • Branch naming:
    • NEW_my_new_functionality
    • IMP_my_functionality_improvement
    • REF_my_code_improvement
    • FIX_the_bug_i_fixed
  • Open a PR as soon as you create the branch
    • Decide the PR is Ask or Show
    • A PR template is provided
  • Keep feature branches short in time and content
  • Long lived branches are hard to merge, to ease integration of unfinished features we recommend:
    • Hide the feature from the user or use a feature flag until ready
    • Keep your branch ready to merge by avoiding code breaking commits
  • Rebase often (~daily) your branch on main during its development
    • Your commits will be reapplied on top of main
      • Ensure your local main and feature branches are updated to last remote version
      • Ensure you are on your feature branch
      • git rebase origin/main --autostash
      • git push -f Caution, just in the feature branch, not main
    • You will have to solve any conflicts your commits create with already integrated code.
      • Reduces merge tension with wide changes already integrated on master
      • Increases merge tension of your wide changes, you will want to integrate
  • Integrate into main
    • Review your changes are in CHANGES.md under ## Unreleased
    • Ensure you have all remote changes with git fetch
    • Do a last rebase on origin/master before merging
    • Merge with --no-ff

Commits

  • Keep commits small enough for the reviewers to identify the change in the diff
  • Do not mix styling with real changes to avoid masking the latter within the diffs
  • Prefix first line of the commit message with a emoji identifying the type of commit:
    • ✨ feat 🐛 fix 🏗 build 🔧 ci 📝 docs
    • ⚡ perf ♻ refactor 🎨 style 🧹 cleanup
    • ✅ test 🚧 wip 🌐 i18n
  • Separate the first line and the body with a blank line
  • Use the body to justify the reasons to reviewers and enumerate changes that are not in the header line
  • Use lightly markdown to format the body (lists...)
  • Acknoledge coauthors with lines like: Co-authored-by: Meregildo <meregildo.obsidiana@somenergia.coop>

Releasing

  • Releases are done in the main branch
  • Decide the new version number M.m.p using semantic versioning
    • M (major) backward incompatible changes or major rewrite
    • m (minor) backward compatible new features
    • p (patch) backward compatible bug fixes
  • Change the version in package.json
  • Review CHANGES.md:
    • Add any user significant changes to the ## Ureleased section on the top of the file
    • Document any changes relevant to deployers (configuration, layout...) under a point named "Upgrade notes".
    • Rename the title ## Unreleased as ## M.m.p (YYYY-MM-DD) (Year, month, day)
  • Bump commit and tag:
    • git commit -m "🏗️ bump to M.m.p" package.json CHANGES.md
    • git push
    • git tag solidar-M.m.p
    • git push --tags

Deploying on server

npm run build
# TODO