|
| 1 | +## Steps to Contribute |
| 2 | + |
| 3 | +Fixes and improvements can be directly addressed by sending a Pull Request on GitHub. Pull requests will be reviewed by one or more maintainers and merged when acceptable. |
| 4 | + |
| 5 | +We ask that before contributing, please make the effort to coordinate with the maintainers of the project before submitting large or high impact PRs. This will prevent you from doing extra work that may or may not be merged. |
| 6 | + |
| 7 | +Use your judgement about what constitutes a large change. If you aren't sure, send a message to the **#litmus-dev** slack or submit an issue on GitHub. |
| 8 | + |
| 9 | + |
| 10 | +### **Sign your work with Developer Certificate of Origin** |
| 11 | + |
| 12 | +To contribute to this project, you must agree to the Developer Certificate of Origin (DCO) for each commit you make. The DCO is a simple statement that you, as a contributor, have the legal right to make the contribution. |
| 13 | + |
| 14 | +See the [DCO](https://developercertificate.org/) file for the full text of what you must agree to. |
| 15 | + |
| 16 | +To successfully sign off your contribution you just add a line to every git commit message: |
| 17 | + |
| 18 | +```git |
| 19 | +Signed-off-by: Joe Smith <[email protected]> |
| 20 | +``` |
| 21 | + |
| 22 | +Use your real name (sorry, no pseudonyms or anonymous contributions.) |
| 23 | + |
| 24 | +If you set your `user.name` and `user.email` git configs, you can sign your commit automatically with `git commit -s`. You can also use git [aliases](https://git-scm.com/book/tr/v2/Git-Basics-Git-Aliases) like `git config --global alias.ci 'commit -s'`. Now you can commit with git ci and the commit will be signed. |
| 25 | + |
| 26 | +## **Development Guide** |
| 27 | + |
| 28 | +Start MongoDB, Auth and GraphQL server as mentioned in the [ChaosCenter Development Guide](https://github.com/litmuschaos/litmus/wiki/ChaosCenter-Development-Guide) to set up the basic structure of the DB. Then start the upgrade manager located in `chaoscenter/upgrade-agents/control-plane` by setting up the environment variables |
| 29 | + |
| 30 | +``` |
| 31 | +export DB_SERVER="mongodb://m1:27015,m2:27016,m3:27017/?replicaSet=rs0" |
| 32 | +export DB_USER=admin |
| 33 | +export DB_PASSWORD=1234 |
| 34 | +export VERSION=<Version you need to upgrade to> |
| 35 | +``` |
| 36 | +To run the upgrade-manager, run |
| 37 | + |
| 38 | +``` |
| 39 | +go run main.go |
| 40 | +``` |
| 41 | +The upgrade-manager would get the current version of Litmus through the DB. |
| 42 | + |
| 43 | +## **Version Upgrade Files** |
| 44 | + |
| 45 | +`<version>/` folder contains files for the upgrade logic |
| 46 | + |
| 47 | +- `upgrade-manager.go` - Contains a map of versions with their corresponding version-managers for the versions. |
| 48 | +- `vx.y.z/manager.go` - Instantiates the Version Manager and runs the upgradeExecutor in transactions which can be omitted if the operation doesn't support a transaction. |
| 49 | +- `vx.y.z/upgrade.go` - Contains the logic of upgradeExecutor of what schema changes are to be made in the specific version. |
| 50 | + |
| 51 | +There are some other files not mentioned here. |
| 52 | + |
| 53 | +## **Example: Upgrade to version 3.9.0** |
| 54 | + |
| 55 | +In version 3.9.0 the following changes are done in DB schema |
| 56 | + |
| 57 | +- In projects collection (auth DB), member role is updated from `Editor` to `Executor` |
| 58 | +- New `is_initial_login` field in users collection (auth DB) whose value is set as false |
| 59 | + |
| 60 | +Run the upgrade-agent while specifying the version `VERSION=3.9.0` in the environmental variable, and it should now be upgraded. |
| 61 | + |
| 62 | +## **Best Practices** |
| 63 | + |
| 64 | +1) If upgrade volume is huge, then transaction is not favorable. |
| 65 | +2) Split the upgrades into proprietary functions depending on their purpose and database/collection names. |
| 66 | +3) Use logging techniques as used in other versions to provide the user an insight of how the upgrades are being done. |
| 67 | +4) While using a transaction, make sure the session context is properly passed into the relevant mongo operations and related functions. |
| 68 | +5) Script should be written in a way that even if run twice, should not affect the already updated documents. |
| 69 | + |
| 70 | + |
| 71 | +Below is the basic technical flow for the upgrade-agent |
| 72 | + |
| 73 | + |
0 commit comments