CONTRIBUTING.md

Contributing to if-plugins

First off, thanks for taking the time to contribute! 🎉

The following document is a rule set of guidelines for contributing.

Table of Contents

• Code Contributions
  • Step 1: Clone
  • Step 2: Branch
  • Step 3: Commit
  • Step 4: Sync
  • Step 5: Push
  • Step 6: Pull Request
• Commit message guidelines
• Coding guidelines
  • Code structuring patterns
    • Object Oriented Programming
    • Functional Programming
  • Naming patterns
  • Documentation
  • Writing tests

Code Contributions

Step 1: Clone

Clone the project on GitHub

$ git clone [email protected]:Green-Software-Foundation/if-plugins.git
$ cd if-plugins

For developing new features and bug fixes, the development branch should be pulled and built upon.

Step 2: Branch

Create new branch from main (staging or master), which will contain your new feature, fix or change.

```bash
$ git checkout -b <topic-branch-name>
```

Step 3: Commit

Make sure git knows your name and email address:

$ git config --global user.name "Example User"
$ git config --global user.email "[email protected]"

Commiting multiple files with changes on multiple resources is not allowed. Commit message should clearly describe on which resource changes are made.

Add and commit:

$ git add my/changed/files
$ git commit

Commit your changes in logical chunks. Please do not push all changes in one commit.

Run yarn fix before commiting for not having conflict with CI linter.

Please adhere to these Commit message guidelines or your code is unlikely be merged into the main project.

Step 4: Sync

Use git pull/merge to synchronize your work with the main repository.

$ git pull origin dev

Step 5: Push

Push your topic branch:

$ git push origin <topic-branch-name>

Step 6: Pull Request

Open a Pull Request with a clear title and description according to template.

Pull request should pass all CI which are defined, should have at least one approve. It should adher to the specification for getting approved.

CI included lint checks, running tests, and etc.

Commit message guidelines

The commit message should describe what changed and why.

1. The first line should:

   • contain a short description of the change
   • be 60 characters or less
   • be prefixed with the name of the changed subsystem
   • be entirely in lowercase with the exception of proper nouns, acronyms, and the words that refer to code, like function/variable names Examples:

    util: add getInitializedModel method to plugins.
    deps: add express package to dependencies.
    service: refactor get user.
   

2. Keep the second line blank.

3. Wrap all other lines at 72 columns:

   • describe each line in logical chunks
   • start each line with: space hyphen space ( - ...)
   • be entirely in lowercase with the exception of proper nouns, acronyms, and the words that refer to code, like function/variable names

   Examples:

     - remove deprecated logger
     - refactor some method
     - add JSDoc on existing function
   

Coding guidelines

Code structuring patterns

Avoid having functions which are responsible to do multiple things at the same time. Make sure one function/method does one thing, and does it well.

Object Oriented Programming

While following Object Oriented Programming paradigm, it's important to follow SOLID principles.

Functional Programming

When designing module of the application in Functional Programming paradigm, the key to follow basic principles.

Naming patterns

Make sure your class/function/variable describes exactly what it does. Avoid using shortened words like txt, arr while doing naming decision. As a naming pattern camel case should be used.

❌ const a = "<MOCK_VALUE_HERE>"
✅ const mockValue = "<MOCK_VALUE_HERE>"

❌ const a = (txt: string) => console.log(txt)
✅ const logMessage = (message: string) => console.log(message)

Documentation

Every logical unit (Class, function, method) should be covered with appropriate documentation. For documenting such, multi-line comment style is used.

❌ const a = (message: string) => console.log(message)

✅
/**
 * Logs given `message` to console.
 **/
const logMessage = (message: string) => console.log(message)

For documenting variable, expression, single line comments can be used after declaration.

class MockClass {
     // this is a mock field
  ❌ private mockField: string = "mock-field"
  ✅ private mockField: string = "mock-field" // Single line documenting style is used.
}

Writing tests

One test file should be responsible for one module. describe blocks should be used for module and function/method description. First describe should follow resource/module: pattern. Second describe title should follow method(): pattern. Test units can use either test or it, title should exactly describe behaviour and input argument. Make sure each test case covers one branch.

See example:

describe('util/args: ', () => {
   describe('parseProcessArgument(): ', () => {
      it('logs help message if property present in env.', () => {
         ...
      })
   })
})

⬅️ back to the root