Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
214 lines (150 loc) · 9.66 KB

CONTRIBUTING.md

File metadata and controls

214 lines (150 loc) · 9.66 KB

Contributing to Blocksense

Welcome and thank you for your interest in contributing to Blocksense! We appreciate your support.

Reading and following these guidelines will help us make the contribution process easy and effective for everyone involved.

Report a bug

  1. Check on the GitHub issue tracker if your bug was already reported.

  2. If you were not able to find the bug or feature open a new issue

  3. Once submitted, do not expect issues to be picked up or solved right away. The only way to ensure this, is to work on the issue yourself.

Report a security vulnerability

Please see our security policy.

Making changes to Blocksense

  1. Search for related issues that cover what you're going to work on. It could help to mention there that you will work on the issue.

    We strongly recommend first-time contributors not to propose new features but rather fix tightly-scoped problems in order to build trust and a working relationship with maintainers.

    Issues labeled good first issue should be relatively easy to fix and are likely to get merged quickly. Pull requests addressing issues labeled idea approved are especially welcomed by maintainers and will receive prioritized review.

    If there is no relevant issue yet and you're not sure whether your change is likely to be accepted, open an issue yourself.

  2. Check for pull requests that might already cover the contribution you are about to make. There are many open pull requests that might already do what you intend to work on. You can use labels to filter for relevant topics.

  3. Make your change!

    3.1 Setup a dev environment
    3.2 Read our GitHub style guide - Branch Naming & Commit Guidelines
    3.3 Implement your changes
    3.4 Confirm that everything works by running tests and local simulations

  4. If the current tests don't cover your changes, add new ones!

  5. Create a pull request for your changes.

    • Clearly explain the problem that you're solving.

      Link related issues to inform interested parties and future contributors about your change. If your pull request closes one or multiple issues, mention that in the description using Closes: #<number>, as it will then happen automatically when your change is merged.

    • Credit original authors when you're reusing or building on their work.

    • Link to relevant changes in other projects, so that others can understand the full context of the change in the future when you or someone else will change or troubleshoot the code. This is especially important when your change is based on work done in other repositories.

      Example:

      This is based on the work of @user in <url>.
This solution took inspiration from <url>.

Co-authored-by: User Name <user@example.com>

      When cherry-picking from a different repository, use the -x flag, and then amend the commits to turn the hashes into URLs.

    • Make sure to have a clean history of commits on your branch by using rebase.

    • Mark the pull request as draft if you're not done with the changes.

  6. Do not expect your pull request to be reviewed immediately.

    Following this checklist will make the process smoother for everyone:

    • Fixes an idea approved issue
    • Add new tests if necessary and make sure all existing pass
    • Update relevant documentation/readme files
    • Code and comments are self-explanatory
    • Commit message explains why the change was made

  7. If you need additional feedback or help to getting pull request into shape, ask other contributors using @mentions.

🌿 Branch Naming & Commit Guidelines

🔹 Branch Naming Convention

  • Use hyphens to separate words.
  • Prefix branches with a type: feature/, fix/, docs/, style/, refactor/, test/, chore/.
  • Followed by a brief description.

📌 Example:

Documentation Website Branch Naming

  • docs.ws/feat/
  • docs.ws/fix/
  • docs.ws/docs/
  • docs.ws/style/
  • docs.ws/refactor/
  • docs.ws/test/
  • docs.ws/chore/

Explorer Website Branch Naming

  • explorer.ws/feat/
  • explorer.ws/fix/
  • explorer.ws/docs/
  • explorer.ws/style/
  • explorer.ws/refactor/
  • explorer.ws/test/
  • explorer.ws/chore/

💾 Formatting & Saving Code Before Commit

Before committing, format your code using:

yarn format:write

✨ Commit Messages

<type><scope>: <subject>

[optional body]

[optional footer(s)]

  • Use present tense ("Add feature" not "Added feature").

  • Use imperative mood

  • NOT end with a .

  • Capitalize the first letter of the message.

  • Keep messages concise but descriptive.

  • Reference issues and pull requests when applicable.

  • Follow this structure: type(scope): subject

    • Type: feat, fix, docs, style, refactor, perf, ci, build, update, config, chore, test
    • Scope: The part of the project the change affects (optional)
    • Subject: A brief description of the change

  • Body is a long form explanation of the change. It should answer the following questions:

    • Why have I made these changes? / Why the change was needed?
    • What you did, what effect have my changes made?
      • Bad example: Change div class a to b
      • Better example: Fix “description” and “about us” paragraphs from overlapping on mobile devices
    • (optional) How you solved the problem? For most changes, it is obvious
    • What are the changes in reference to?

  • Footers

    • Must be parse-able by git interpret-trailers
    • BREAKING CHANGE: - needed for commits

Commit Types

  • feat (feature) - Add new user-facing functionality or update a public API.
    • If the commit changes a library (and so its users are developers, not actual end-users), feat relates to its public API
    • Similarly, for backend services, changes to the REST/GraphQL/RPC/etc. API should be marked as feat
    • A repository which is a collection of packages (e.g. ethereum.nix), adding a new package
  • fix (bug fix) - Resolve a bug in existing functionality.
  • docs (documentation) - Modify or add documentation.
  • style (code style) – Reformat code, update comments, or make stylistic changes that do not affect behavior.
  • refactor (refactoring) – Improve code structure without changing functionality.
  • perf (performance) – Optimize performance or efficiency.
  • ci (continuous integration) – Modify CI/CD pipeline configurations or workflows.
  • build (build system) – Modify build scripts, dependencies, or package configurations.
  • update (dependency update) – Update the version of a dependency.
  • config (configuration) – Modify system or application configuration settings.
  • chore (maintenance) – Miscellaneous tasks that do not fit other types, such as renaming files or minor internal changes.
  • test (testing) – Add or update tests, but not changing implementation.

📌 Example:

Documentation Website Specific Commits

  • feat(docs.ws):
  • fix(docs.ws):
  • docs(docs.ws):
  • style(docs.ws):
  • refactor(docs.ws):
  • test(docs.ws):
  • chore(docs.ws):
  • build(docs.ws):
  • config(docs.ws):

Explorer Website Specific Commits

  • feat(explorer.ws):
  • fix(explorer.ws):
  • docs(explorer.ws):
  • style(explorer.ws):
  • refactor(explorer.ws):
  • test(explorer.ws):
  • chore(explorer.ws):
  • build(explorer.ws):
  • config(explorer.ws):

Common Updates in the Blocksense Docs Theme Folder

  • feat(docs.theme):

✅ Following these conventions ensures better collaboration, cleaner history, and easier code reviews. 🚀

Getting help

Whenever you're stuck or do not know how to proceed, you can always ask for help. We invite you to use our public Discord to ask questions.

Git Tips & Tricks