code/network-generator/CONTRIBUTING.md

   1 # How to develop on this project
   2
   3 network_generation welcomes contributions from the community.
   4
   5 **You need PYTHON3!**
   6
   7 This instructions are for linux base systems. (Linux, MacOS, BSD, etc.)
   8 ## Setting up your own fork of this repo.
   9
  10 - Clone this repo.
  11 ```
  12   git clone "https://gerrit.o-ran-sc.org/r/oam" && (cd "oam" && mkdir -p `git rev-parse --git-dir`/hooks/ && curl -Lo `git rev-parse --git-dir`/hooks/commit-msg https://gerrit.o-ran-sc.org/r/tools/hooks/commit-msg && chmod +x `git rev-parse --git-dir`/hooks/commit-msg)
  13 ```
  14 - Enter the directory `cd oam/code/network-generation`
  15 - Please see [O-RAN-SC Code Contributions Tutorial](https://wiki.o-ran-sc.org/display/ORAN/Tutorial%3A+Making+code+contributions+to+O-RAN+open+source+project)
  16
  17 ## Prerequisites
  18
  19 ```
  20 pip install isort
  21 pip install black
  22 pip install mypy
  23 pip install flake8
  24 pip install pytest
  25 pip install coverage
  26 pip install pytest-cov
  27 ```
  28
  29 ## Setting up your own virtual environment
  30
  31 Run `make virtualenv` to create a virtual environment.
  32 then activate it with `source .venv/bin/activate`.
  33
  34 ## Install the project in develop mode
  35
  36 Run `make install` to install the project in develop mode.
  37
  38 ## Run the tests to ensure everything is working
  39
  40 Run `make test` to run the tests.
  41
  42 ## Create a new branch to work on your contribution
  43
  44 Run `git checkout -b my_contribution`
  45
  46 ## Make your changes
  47
  48 Edit the files using your preferred editor. (we recommend VIM or VSCode)
  49
  50 ## Format the code
  51
  52 Run `make fmt` to format the code.
  53
  54 ## Run the linter
  55
  56 Run `make lint` to run the linter.
  57
  58 ## Test your changes
  59
  60 Run `make test` to run the tests.
  61
  62 Ensure code coverage report shows `100%` coverage, add tests to your PR.
  63
  64 ## Build the docs locally
  65
  66 Run `make docs` to build the docs.
  67
  68 Ensure your new changes are documented.
  69
  70 ## Commit your changes
  71
  72 This project uses [conventional git commit messages](https://www.conventionalcommits.org/en/v1.0.0/).
  73
  74 Example: `fix(package): update setup.py arguments 🎉` (emojis are fine too)
  75
  76 ## Push your changes to your fork
  77
  78 Run `git push origin my_contribution`
  79
  80 ## Submit a pull request
  81
  82 On github interface, click on `Pull Request` button.
  83
  84 Wait CI to run and one of the developers will review your PR.
  85 ## Makefile utilities
  86
  87 This project comes with a `Makefile` that contains a number of useful utility.
  88
  89 ```bash
  90 ❯ make
  91 Usage: make <target>
  92
  93 Targets:
  94 help:             ## Show the help.
  95 install:          ## Install the project in dev mode.
  96 fmt:              ## Format code using black & isort.
  97 lint:             ## Run pep8, black, mypy linters.
  98 test: lint        ## Run tests and generate coverage report.
  99 watch:            ## Run tests on every change.
 100 clean:            ## Clean unused files.
 101 virtualenv:       ## Create a virtual environment.
 102 release:          ## Create a new tag for release.
 103 docs:             ## Build the documentation.
 104 switch-to-poetry: ## Switch to poetry package manager.
 105 init:             ## Initialize the project based on an application template.
 106 ```
 107
 108 ## Making a new release
 109
 110 This project uses [semantic versioning](https://semver.org/) and tags releases with `X.Y.Z`
 111 Every time a new tag is created and pushed to the remote repo, github actions will
 112 automatically create a new release on github and trigger a release on PyPI.
 113
 114 For this to work you need to setup a secret called `PIPY_API_TOKEN` on the project settings>secrets,
 115 this token can be generated on [pypi.org](https://pypi.org/account/).
 116
 117 To trigger a new release all you need to do is.
 118
 119 1. If you have changes to add to the repo
 120     * Make your changes following the steps described above.
 121     * Commit your changes following the [conventional git commit messages](https://www.conventionalcommits.org/en/v1.0.0/).
 122 2. Run the tests to ensure everything is working.
 123 4. Run `make release` to create a new tag and push it to the remote repo.
 124
 125 the `make release` will ask you the version number to create the tag, ex: type `0.1.1` when you are asked.
 126
 127 > **CAUTION**:  The make release will change local changelog files and commit all the unstaged changes you have.