OmdenaLore Guidelines

Introduction

As the name suggests, OmdenaLore is a body of knowledge held by Omdena. OmdenaLore is a library/package that contains code knowledge base gathered in completed and ongoing projects. The code knowledge base increases and gets updated as collaborators add their knowledge. OmdenaLore is a collaborator sourced structured library.

Guidelines

How to contribute to OmdenaLore

If you have a code block that can help collaborators in current or future projects, you can add that code block to the OmdenaLore repository. The contributions to OmdenaLore repository go through peer-to-peer reviews, more details below. To make sure a valid contribution is made, please follow the steps below.

Clone of the repository from DAGsHub https://dagshub.com/Omdena/OmdenaLore
1. You can clone the repository locally with the following command in your terminal/Powershell: git clone https://dagshub.com/Omdena/OmdenaLore.git
2. If you are not comfortable with the terminal, you can use the GitHub desktop option as well.
After localizing the repository, we recommend that you open a issue explaining what you are working on. Since OmdenaLore is a collaborative platform, we wish to have great communication between you and fellow contributors and opening an issue is a good way to do so.
1. To open an issue, head to dagshub.com/omdenalore and click on the issue section. Create or find an issue according to your problem statement.
Once inside the local folder of the repository, make a new git branch from the main branch. Let’s say you are adding code to the nlp folder and you would like to make a nlp-contrib branch. You can do this with the following command - git checkout -b nlp-contrib . To quickly familiarize yourself with git branches, read this official primer here.
1. We recommend that you make a branch with your own name or the issues that you are working on. Example branch names - issues_44, john_doe, …
After you’ve made your desired changes in your branch, it is time to push the branch to the DAGsHub repository online. To push your changes you can use GitHub desktop to add, commit, and push your changes or use your terminal/Powershell. For more information on how to use git, please refer to these docs: https://github.com/git-guides/git-add, https://github.com/git-guides/git-commit, https://github.com/git-guides/git-push.
If you are the first one to work on that branch, it does not exist yet on DAGsHub. When you try the git push command, you might hit this error:

In this example, the branch example-branch is unrecognized by the repository online. To fix this error, run the command git automatically recommends, which in the case shown above would be: git push –set-upstream origin example-branch
Once you have pushed your branch successfully, it is time to open a Pull Request on DAGsHub.
1. On the repository webpage, go to the Pull Requests section.
1. Click on New Pull Request
1. On the right side of the webpage, pick the branch you want to open a Pull Request with. This branch contains the changes you are requesting to be merged into the main branch of the repository. Search for the name of your branch and select it.
1. IMPORTANT: This step is of utmost importance for your Pull Request’s final phase. Make sure you are adequately documenting your Pull Request with clear and concise summary points on the changes you have made. You can even upload images in this process. This will help the Pull Request reviewers understand the changes and request any changes if required. In the example below, I am making a Pull Request for my docs-update branch. Please find more information on the PR template here.
1. Notice the Assignee option on the right side. Here you can click on Assign and assign another collaborator you are working with if you wish to request feedback about the Pull Request or even request additional features on top of your changes. Here I assigned the Pull Request to my colleague to get this feedback on my changes.
That’s it! Now you can click Create Pull Request and share your Pull Request link in the slack channel. One of the reviewers will get to it and share their feedback with you and request to make any adjustments if required. After that, your PR will be merged into the main branch.

Pull request guidelines and templates

Whenever a pull request (PR) is generated, it’s highly recommended for collaborators to include as many of these sections in the PR description. It makes PR approval and review process faster and efficient.

How to format your Pull Requests

Branching Conventions

The main Python version of the package will be 3.7

main branch contains the published repository code
The rest of the branches will correspond to specific omdenalore versions such as 0.2.x, 0.3.x, etc.
A branch will be created for each feature/bug fix where a single thing is being done only.

For example `0.2.3` consists of refactoring optical_character_recognition once it is done it is merge with `0.2.x` which will contain the main code for version `0.2`
After the refactoring and testing stage is completed all branches, except version numbers and the main branch will be deleted from the entire repository
Collaborators will have to create a virtual environment and then install all the packages using the `requirements.txt` file and if new libraries are installed they have to be added to the `requirements.txt`

Contribution Workflow

Setup Your Local Environment

Create a conda or venv environment
```
conda create --name <name> python=3.7
```
Make sure that you use python 3.7 ONLY
```
python3 -m venv <myenvname>
```
pip install -r requirements.txt
Every time a new library is added you will need to update the requirements.txt

During code development

Pull the latest from upstream:

git checkout main
git pull upstream main

Create a branch for the feature that you are working on(if the branch names for refactoring or testing are already planned out then follow them)
```
git checkout -b <branch_name>
```
Commit locally and add them to your branch
Make sure that each commit contains a single logically piece of work and the commit message reflects what was done efficiently.
We use pre-commit hooks when committing to make sure that the code passes some set rules. To get the pre-commit hooks up and running please refer to this PR

Submit your contribution

When you’re done, make a PR with the branch that you wish to merge with, for example if you are working on OmdenaLore 0.3.1 then this would be merged into OmdenaLore 0.3.x

Check this section if you want to know how to create PR How to contribute to OmdenaLore and Pull request guidelines and templates

Review Process

The reviewing team will be reviewing each PR and will help you improve the implementation, documentation and style of the PR.

If changes are needed, make the changes and push to the branch where the update will be reflected in the PR automatically. Once the PR is approved then the reviewing team will merge the PR.

Things to ensure

All code should have tests.

Check this section for more information -> Testing your code
All code should be documented, using the Sphinx format.
Setup your editor to follow PEP 8.
We use black for formatting and flake8 for linting

How to format doc strings

The doc strings follows rst format. For more information and example visit these sites.

Thomas-cokelear

anaconda docs

Testing your code

To Test your code, follow the documentation below

Testing Guidelines