Thanks for your interest in registry-cli! You can contribute in any of the
following ways:
- Reporting bugs
- Improving documentation
- Fixing bugs
- Adding new features
Open an issue using the Bug Report template
here!
Documentation is in the form of markdown files in the docs directory of the
repository. Feel free to edit it to:
- to make the docs clearer/easier to understand
- fix typos
- add a section about something new
- add something that was previously left out of docs
The CLI is written in Typescript. To contribute to code, first setup your dev environment.
This guide assumes a some familiarity with basic linux commands. If not, here is a great place to start.
Linux and MacOS will have a terminal installed already. For Windows, it is
recommended that you use git-bash, which you can install from
here.
Type echo Hi in the terminal once it is installed. If installed correctly, you
should see Hi appear when you hit enter.
Installation instructions for Git can be found here.
Run git --version in the terminal if Git has been installed correctly:
$ git --version
git version 2.33.0Installation instructions for NodeJS can be found
here. We use the LTS version
of NodeJS (16.x) for developing the CLI.
Run node --version in the terminal if NodeJS has been installed correctly:
$ node --version
v16.20.2Once NodeJS is installed, run the following in terminal to install PNPM:
$ sudo npm install --global pnpmRun pnpm --version in the terminal if PNPM has been installed correctly:
$ pnpm --version
8.15.4Installation instructions for Docker can be found here.
Run docker --version in terminal to check if Docker has been installed
correctly:
$ docker --version
Docker version 20.10.10, build b485636f4bInstallation instructions can be found here.
Run docker-compose --version in terminal to check if Docker Compose has been
installed correctly:
$ docker-compose --version
Docker Compose version 2.0.1Once you have your installed all of the above tools, fork the repository on Github: https://github.com/Sunbird-RC/registry-cli. For instructions on how to fork a repository, read through this.
Then, clone the repository on your computer using git:
$ git clone [email protected]:<your github username>/registry-cli.git sunbird-rc-registry-cliThis will create a directory called sunbird-rc-registry-cli, which contains
the registry as well as the source code to run the CLI. Move into the directory
which contains the CLI's code by typing the following:
$ cd sunbird-rc-registry-cliThen, add the upstream remote so you can fetch the latest changes from the
main repository and merge them into your fork:
$ git remote add upstream [email protected]:sunbird-rc/registry-cli.gitTo merge the latest changes into your fork anytime, run:
$ git pull upstream main
$ git rebase -iTo keep your development environment organized, create local branches to hold
your work. These should be branched directly off of the main branch. While
naming branches, try to name it according to the bug it fixes or the feature it
adds. Also prefix the branch with the type of change it is making. Here is a
list of common prefixes:
| Name | Description |
|---|---|
fix |
A bug fix/improvement |
feature |
A new feature |
docs |
A documentation change |
perf |
A code change that improves performance |
refactor |
A code change that neither fixes a bug nor adds a feature |
test |
A change to the tests |
style |
Changes that do not affect the meaning of the code (linting) |
To create a branch and switch to it, run the following:
$ git checkout -b my/branch -t upstream/mainTo make sure you can run your development version of the CLI using the
registry command, run the following commands in the registry-cli folder:
# In case you have already installed the CLI from npm, remove it
$ sudo npm rm -g registry-cli
# Install dependencies
$ pnpm install
# Creates a global symlink to the current directory
$ sudo pnpm i -g `pwd -P`
# Watches the files for changes and recompiles the CLI if it detects any changes
$ pnpm watchNow you can make changes to the source code, and test the CLI using the
registry command.
The source directory looks something like this:
src
├── commands
│ └── ...
├── extensions
│ └── cli-extension.ts
├── templates
│ └── ...
├── toolbox
│ └── ...
├── cli.ts
└── types.ts
- The
commandsdirectory contains code for each command. - The
extensions/cli-extension.tsfile contains the code that registers the extensions from thetoolboxdirectory. - The
toolboxfolder contains the actual code to create and manage registry instances using docker. - The
templatesfolder contains the files required to setup an example registry. - The
cli.tsfile contains code to initialize the CLI. - The
types.tsfile contains necessary types for the CLI.
Once your changes are ready to go, begin the process of documenting your code. The code must be well commented, so future contributors can move around and make changes easily.
Once you are done documenting code, run the formatter, linter and tests:
$ pnpm testPlease ensure that the tests pass! To fix some issues automatically, try running:
$ pnpm lintIt is recommended to keep your changes grouped logically within individual commits. Many contributors find it easier to review changes that are split across multiple commits. There is no limit to the number of commits in a pull request.
$ git add my/changed/files
$ git commit -m 'commit message...'
Note that multiple commits often get squashed when they are landed.
Please follow the conventional commit style when writing commit messages.
Once you have documented your code as required, begin the process of opening a pull request by pushing your working branch to your fork on GitHub.
$ git push origin my/branch
From within GitHub, opening a
new pull request will
present you with a template that should be filled out. Remember to mention
@gamemaker1 so I can give you feedback as soon as possible!
You will probably get feedback or requests for changes to your pull request. This is a big part of the submission process, so don't be discouraged! Some contributors may sign off on the pull request right away. Others may have detailed comments or feedback. This is a necessary part of the process in order to evaluate whether the changes are correct and necessary.
To make changes to an existing pull request, make the changes to your local branch, add a new commit with those changes, and push those to your fork. GitHub will automatically update the pull request.
$ git add my/changed/files
$ git commit
$ git push origin my/branchThere are a number of more advanced mechanisms for managing commits using
git rebase that can be used, but are beyond the scope of this guide. Also, any
branch that is being merged must be merged without fast forward, i.e.,
git merge --no-ff ....
Feel free to post a comment in the pull request to ping reviewers if you are awaiting an answer on something.
Approval and Request Changes Workflow
All pull requests require approval from at least one maintainer in order to land. Whenever a maintainer reviews a pull request they may request changes. These may be small, such as fixing a typo, or may involve substantive changes. Such requests are intended to be helpful, but at times may come across as abrupt or unhelpful, especially if they do not include concrete suggestions on how to change them.
Try not to be discouraged. Try asking the maintainer for advice on how to implement it. If you feel that a review is unfair, say so or seek the input of another project contributor. Often such comments are the result of a reviewer having taken insufficient time to review and are not ill-intended. Such difficulties can often be resolved with a bit of patience. That said, reviewers should be expected to provide helpful feedback.
In order to land, a pull request needs to be reviewed and approved by at least one maintainer. After that, if there are no objections from other contributors, the pull request can be merged.
Congratulations and thanks a lot for your contribution!
To release a new version of the CLI, run pnpm publish.