Upstream/bitwarden-browser
1
0
Fork 0
mirror of https://github.com/bitwarden/browser.git synced 2024-11-23 11:56:00 +01:00
Code Issues Projects Releases Wiki Activity

Expand CONTRIBUTING.md to include submodule info and workflows (#421)

Browse Source 
* Add guidance for jslib workflows for community

* Minor typos and wording

* Update CONTRIBUTING.md

Co-authored-by: Chad Scharf <3904944+cscharf@users.noreply.github.com>

Co-authored-by: Chad Scharf <3904944+cscharf@users.noreply.github.com>
This commit is contained in:
Thomas Rittson 2021-07-09 08:04:16 +10:00 committed by GitHub
parent 75fff66f98
commit c9b13e4d1b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 47 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
CONTRIBUTING.md
View File

@ -26,44 +26,67 @@ Please sign the [Contributor Agreement](https://cla-assistant.io/bitwarden/jslib
* commit any pull requests against the `master` branch
* include a link to your Community Forums post
# Introduction to jslib and git submodules
jslib is a repository that contains shared code for all Bitwarden Typescript/Javascript clients (web, desktop, browser, CLI, and directory connector). The clients use this code by consuming jslib as a submodule. This makes jslib code available to each client under the `jslib` directory of the client repository.
If you haven't worked with submodules before, you should start by reading some basic guides (such as the [git scm chapter](https://git-scm.com/book/en/v2/Git-Tools-Submodules) or the [Atlassian tutorial](https://www.atlassian.com/git/tutorials/git-submodule)).
# Setting up your Local Dev environment for jslib
In order to easily test, check and develop against local changes to jslib across each of the TypeScript/JavaScript clients it is recommended to use symlinks for the submodule so that you only have to make the change once and don't need to x-copy or wait for a commit+merge to checkout, pull and test against your other repos.
In order to easily develop local changes to jslib across each of the TypeScript/JavaScript clients, we recommend using symlinks for the submodule so that you only have to make the change once for it to be reflected across all your local repos.
## Prerequisites
1. git bash or other git command line
2. In order for this to work well, you need to use a consistent relative directory structure. Repos should be cloned in the following way:
## Clone Repos
In order for this to work well, you need to use a consistent relative directory structure. Repos should be cloned in the following way:
* `./<your project(s) directory>`; we'll call this `/dev` ('cause why not)
* jslib - `git clone https://github.com/bitwarden/jslib.git` (/dev/jslib)
* web - `git clone --recurse-submodules https://github.com/bitwarden/web.git` (/dev/web)
* desktop - `git clone --recurse-submodules https://github.com/bitwarden/desktop.git` (/dev/desktop)
* browser - `git clone --recurse-submodules https://github.com/bitwarden/browser.git` (/dev/browser)
* cli - `git clone --recurse-submodules https://github.com/bitwarden/cli` (/dev/cli)
* `./<your project(s) directory>`; we'll call this `/dev` ('cause why not)
* jslib - `git clone https://github.com/bitwarden/jslib.git` (/dev/jslib)
* web - `git clone --recurse-submodules https://github.com/bitwarden/web.git` (/dev/web)
* desktop - `git clone --recurse-submodules https://github.com/bitwarden/desktop.git` (/dev/desktop)
* browser - `git clone --recurse-submodules https://github.com/bitwarden/browser.git` (/dev/browser)
* cli - `git clone --recurse-submodules https://github.com/bitwarden/cli` (/dev/cli)
You should notice web, desktop, browser and cli each reference jslib as a git submodule. If you've already cloned the repos but didn't use `--recurse-submodules` then you'll need to init those:
`npm run sub:init`
You should notice web, desktop, browser and cli each reference jslib as a git submodule. If you've already cloned the repos but didn't use `--recurse-submodules` then you'll need to init the submodule with `npm run sub:init`.
## Configure Symlinks
Be aware that using git clone will make symlinks added to your repo be seen by git as plain text file paths, lets make sure this is set to true to prevent that. In the project root run, `git config core.symlinks true`.
Using `git clone` will make symlinks added to your repo be seen by git as plain text file paths. We need to prevent that. In the project root run, `git config core.symlinks true`.
For each project other than jslib, run the following:
For macOS/Linux: `npm run symlink:mac`
* For macOS/Linux: `npm run symlink:mac`
* For Windows: `npm run symlink:win`
For Windows: `npm run symlink:win`
Your client repos will now be pointing to your local jslib repo. You can now make changes in jslib and they will be immediately shared by the clients (just like they will be in production).
## Updates and Cleanup
* Need to update parent repo that has jslib as a submodule to latest from actual jslib repo?
* Create branch from master (`git checkout -b update-jslib`)
* From new local branch: `npm run sub:pull` (`git submodule foreach git pull origin master`)
* Follow Pull Request notes for commit/push instructions
* Once merged, pull master, rebase your feature branch and then do npm run sub:update to catch your submodule up
* Discard changes made to a submodule
* `git submodule foreach git reset —hard`
## Committing and pushing jslib changes
* You work on jslib like any other repo. Check out a new branch, make some commits, and push to remote when you're ready to submit a PR.
* Do not commit your jslib changes in the client repo. Your changes to the client and your changes to jslib should stay completely separate.
* When submitting a client PR that depends on a jslib PR, please include a link to the jslib PR so that the reviewer knows there are jslib changes.
### Updating jslib on a feature branch
If you've submitted a client PR and a jslib PR, your jslib PR will be approved and merged first. You then need to update jslib on your client PR.
1. If you've symlinked the client's jslib directory following the steps above, you'll need to delete that symlink and then run `npm run sub:init`.
2. Update the jslib submodule:
* if you're working on your own fork, run `git submodule update --remote --reference upstream`.
* if you're working on a branch on the official repo, run `npm run sub:update`
3. To check you've done this correctly, you can `cd` into your jslib directory and run `git log`. You should see your recent changes in the log. This will also show you the most recent commit hash, which should match the most recent commit hash on [Github](https://github.com/bitwarden/jslib).
4. Add your changes: `git add jslib`
5. Commit your changes: `git commit -m "update jslib version"`
6. Push your changes: `git push`
Once this is complete, your client PR will be ready for final review and merging.
### Updating jslib on a client directly
If you've made changes to jslib without needing to make any changes to the client, then you may be asked to update jslib on the client. This is similar to the above process, except that you'll be creating a new client branch and PR solely for the jslib update.
1. Make sure your local client repo is up to date
2. Create a new branch: `git checkout -b update-jslib`
3. Follow the steps above
4. Create a new PR to the client repo. Please include a link to your jslib PR so that reviewers know why you're updating jslib.
## Merge Conflicts
At times when you need to perform a `git merge master` into your feature or local branch, and there are conflicting version references to the *jslib* repo from your other clients, you will not be able to use the traditional merge or stage functions you would normally use for a file.