1 # How to develop on this project
3 network_generation welcomes contributions from the community.
7 This instructions are for linux base systems. (Linux, MacOS, BSD, etc.)
8 ## Setting up your own fork of this repo.
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)
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)
20 sudo apt install python3.10-venv
23 ## Setting up your own virtual environment
25 Run `make virtualenv` to create a virtual environment.
26 then activate it with `source .venv/bin/activate`.
28 ## Install the project in develop mode
30 Run `make install` to install the project in develop mode.
32 ## Run the tests to ensure everything is working
34 Run `make test` to run the tests.
36 ## Create a new branch to work on your contribution
38 Run `git checkout -b my_contribution`
42 Edit the files using your preferred editor. (we recommend VIM or VSCode)
46 Run `make fmt` to format the code.
50 Run `make lint` to run the linter.
54 Run `make test` to run the tests.
56 Ensure code coverage report shows `100%` coverage, add tests to your PR.
58 ## Build the docs locally
60 Run `make docs` to build the docs.
62 Ensure your new changes are documented.
64 ## Commit your changes
66 This project uses [conventional git commit messages](https://www.conventionalcommits.org/en/v1.0.0/).
68 Example: `fix(package): update setup.py arguments 🎉` (emojis are fine too)
70 ## Push your changes to your fork
72 Run `git push origin my_contribution`
74 ## Submit a pull request
76 On github interface, click on `Pull Request` button.
78 Wait CI to run and one of the developers will review your PR.
81 This project comes with a `Makefile` that contains a number of useful utility.
88 help: ## Show the help.
89 install: ## Install the project in dev mode.
90 fmt: ## Format code using black & isort.
91 lint: ## Run pep8, black, mypy linters.
92 test: lint ## Run tests and generate coverage report.
93 watch: ## Run tests on every change.
94 clean: ## Clean unused files.
95 virtualenv: ## Create a virtual environment.
96 release: ## Create a new tag for release.
97 docs: ## Build the documentation.
98 switch-to-poetry: ## Switch to poetry package manager.
99 init: ## Initialize the project based on an application template.
102 ## Making a new release
104 This project uses [semantic versioning](https://semver.org/) and tags releases with `X.Y.Z`
105 Every time a new tag is created and pushed to the remote repo, github actions will
106 automatically create a new release on github and trigger a release on PyPI.
108 For this to work you need to setup a secret called `PIPY_API_TOKEN` on the project settings>secrets,
109 this token can be generated on [pypi.org](https://pypi.org/account/).
111 To trigger a new release all you need to do is.
113 1. If you have changes to add to the repo
114 * Make your changes following the steps described above.
115 * Commit your changes following the [conventional git commit messages](https://www.conventionalcommits.org/en/v1.0.0/).
116 2. Run the tests to ensure everything is working.
117 4. Run `make release` to create a new tag and push it to the remote repo.
119 the `make release` will ask you the version number to create the tag, ex: type `0.1.1` when you are asked.
121 > **CAUTION**: The make release will change local changelog files and commit all the unstaged changes you have.