Welcome Contributer,

this document contains the Contribution Guidelines for the repo and how to test the changes before submitting a merge request.

Table of Contents

  1. Contributions
    1. Base Class
    2. Test Class
    3. Documentation
    4. Code Refactor
  2. Testing
  3. Merge Request
  4. Code Style
  5. Contributer Ettiqute

1. Contributions

the repo is open to everyone to contribute as they fit. but we have identified some base level contributions which will keep the test, release builds more stable.

each kind of contribution will be discussed in detail and these guidelines have to be followed.

1. Base Class

Base Classes involve contribution of class abstractions to any of the folders inside taiyo_utils. the rules for the class abstractions vary depending on the kind of class being contributed. as for the structure of the class and the rules for that will present in the following document. click here to access it.

2. Test Classes

Test Classes are important inorder to ensure quality of the base classes contributed in the repo. so its important for any base class contribution to have a test class submitted along with it. as for the structure of the class and the rules for that will present in the following document. click here to access it.

3. Documentation

Documentation is very important and helps new contributers get in touch with what the repo has to offer and decide which portions they can contribute.

we dont use complicated docs software like sphinx for our purpose (delayed untill further notice), but write basic simple enough documentation for the classes as docstrings and markdown files in the docs folder in the repo.

markdown is easy to pick up and is almost universal in the coding community in case you are looking for a guide here is one.

4. Code Refactor

Code Maintainance and Refactor is always a recurring task and most of the contribution comes in this form. we follow a TDD(Test Driven Development) Approach to refactor the code and it saves a lot of time in validating the contributions and keeps the builds stable.

the above diagram basically sums up the entire life cycle of code refactoring using TDD. if you need more understanding on tdd here is one to start with.

The refactoring can be done on any of the base classes in the repo.

2. Testing

Testing the repo for stability and quality is important and any request for a feature must be made clear. make sure the request handles all the base exceptions and keeps the code reliable.

for this make sure the tests written in the tests folder all pass or atleast the section in which the contribution is made.

we use unittests for now to do a unit level testing of our classes. so we highly urge to set it up in the editors and discover the tests present in the tests folder.

after making sure the tests are fine you can proceed to make a merge request.

3. Merge Requests

Merge Request is the final stage of submitting a contribution to the repository and its important to keep a consistent check list before submitting the code

the check list can be found here. make sure your contribution follows all this before posting the request in repo.

4. Code Styles

Code style is always important to keep a repo more consistent, clean and also encouraging people to understand the use of a certain contribution.

so here are some to take care of when you are working with the code. - Always use a linter with your code editor. there are a wide variety of linters out there. this repo uses flake8 linter so make sure to install that when working with the code. - The comments structure for the code is always important. we follow Google Docstring format for commenting the class definitions and functions. keeps the sections more consistent and easy to follow. - Use Intention-Revealing Names for the functions and variables that are added in the code. - Classes should be small - Functions should be small - Function should do one thing - Avoid Duplication - Proper Exception Handling has to be done often in the code. - Do not log or store highly sensitive information in the code. write the generation document and submit it or use environment variables to mask them. - Always write private functions in classes unless you want to expose a function to be used. - write tests for every function or class implemented. - try to avoid returning null or NoneType objects in the code. unless it cant be helped - use dictionaries as much as possible if you have a lot of constants that you want to map - minimize function calls as much as possible. avoid if it hurts the interpretability.

5. Contributer Etiquette

These are some practices that the contributers have to follow so its easier for everyone to bring that amazing contributions to release.

  • Always ensure the checklists are met before sending out a merge request
  • always make a private branch for each feature you are committing. the branch naming conventions are as follows:
    • feature/\<name of the feature>
    • bug_fix/\<name of the bug>
    • tests/\<name of the tests>
    • base_class/\<name of the base class>
    • docs/\<name of the document>
    • refactor/\<name of the refactored class>
  • Make issues in Gitlab for the bugs that you are facing and send a slack request out in the public channel for everyone to discuss and decide a fix. keep the discussion of this in gitlab issues page rather than on slack.
  • The Maintainer is not always going to be ontime in handling a merge request so be patient about it. he or she too is human.
  • Issues can be open to discuss a idea or a proposal for contribution and its encouraged to do so. but be sure to read the guidelines properly before approaching with a request idea.
  • Follow the guidelines mentioned in the document to ensure the repo stays consistent after the contribution is merged.
  • Make sure to remove sensitive information in the repo.
  • Make sure to remove logs and other artifacts made by the scripts.

Finally we appreciate you for taking intrest in this repo. all the best and Happy Coding!