Skip to content

Commit

Permalink
Update recommendations regarding forks vs branches
Browse files Browse the repository at this point in the history
  • Loading branch information
JunTaoLuo committed Dec 15, 2023
1 parent 6dcc277 commit 020c297
Show file tree
Hide file tree
Showing 2 changed files with 11 additions and 36 deletions.
37 changes: 6 additions & 31 deletions READMES/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,36 +13,17 @@ See [the Codespaces README](./codespaces.md) to get a fully functional cloud-bas

## Step 1: Get Source Code / Git Setup

- Fork the repo by pressing the "Fork" button: [github.com/department-of-veterans-affairs/va.gov-cms](https://github.com/department-of-veterans-affairs/va.gov-cms)
- Clone your fork.
- Clone the repo: [github.com/department-of-veterans-affairs/va.gov-cms](https://github.com/department-of-veterans-affairs/va.gov-cms)
```sh
$ git clone [email protected]:YOUR-GITHUB-USERNAME/va.gov-cms.git
$ git clone [email protected]:department-of-veterans-affairs/va.gov-cms.git
$ cd va.gov-cms
```

* Add upstream repo (Recommended):

```sh
$ git remote add upstream [email protected]:department-of-veterans-affairs/va.gov-cms.git
```
* Optionally rename your fork so its name is more meaningful and ensures your upstream and origin are not misnamed.
```sh
$ git remote rename origin myfork
```
* Verify your remotes, it should list upstream and myfork/origin as remotes.
```sh
$ git remote -v
myfork [email protected]:YOUR_GIT_USERNAME/va.gov-cms.git (fetch)
myfork [email protected]:YOUR_GIT_USERNAME/va.gov-cms.git (push)
upstream [email protected]:department-of-veterans-affairs/va.gov-cms.git (fetch)
upstream [email protected]:department-of-veterans-affairs/va.gov-cms.git (push)
```
* Make sure your local repo is aware of what's on the remotes.
```sh
$ git fetch --all
```
q
* Make sure git is not tracking perms
```sh
$ git config core.fileMode false
Expand All @@ -55,27 +36,21 @@ See [the Codespaces README](./codespaces.md) to get a fully functional cloud-bas
$ git config --global branch.main.rebase true
```
* Make branch main always pulls from the remote: upstream.
```sh
$ git checkout main
$ git branch --set-upstream-to upstream/main
```
* Make changes to simplesaml storage not be tracked locally.
```sh
git update-index --skip-worktree samlsessiondb.sq3
```
You should periodically update your branch from `upstream main` branch:
You should periodically update your branch from `origin main` branch. This will rebase your current branch on top of new commits in main:
```sh
$ git pull upstream main
$ git pull origin main
```
## Step 2: Launch development environment
1. Set ddev environment variables:
1. Set ddev environment variables:
```bash
$ cd va.gov-cms
Expand Down
10 changes: 5 additions & 5 deletions READMES/workflow.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,15 +17,15 @@
1. Write a manual to test ticket completion.

## Git
To avoid cluttering up the repo with lots of branches, fork the repo and push your branches to your fork and make your pull request from your fork to the upstream repo. You can use the GitHub CLI, [`gh`](https://cli.github.com/), to make PRs from the command line much faster. Or after you push you will see a link in the output to ctrl + click and create a new PR from the branch you just pushed. [Getting started](./getting-started.md).
In this repo, we recommend working in individual branches and creating PRs to merge the branches to main. You can use the GitHub CLI, [`gh`](https://cli.github.com/), to make PRs from the command line much faster. Or after you push you will see a link in the output to ctrl + click and create a new PR from the branch you just pushed. See [Getting started](./getting-started.md) for more details.

### Branches
We are currently working off a single `main` branch. `main` is protected and requires both approval from code review and passing tests to be merged. Commits within pull requests are squashed and merged when they are accepted so that the only relate to one git commit, even if they originally contained multiple commits, the commit messages are added as a bulleted list so they are retained in the merge commit.

### Example Git workflow:

1. `git fetch --all`
1. `git checkout -b <VACMS-000-name> upstream/main`
1. `git checkout -b <VACMS-000-name> origin/main`
1. `ddev composer install`
1. `ddev start` or `ddev restart`
1. `ddev pull va --skip-files` or `ddev pull va` idf you need managed files (images and pdfs)
Expand All @@ -34,15 +34,15 @@ We are currently working off a single `main` branch. `main` is protected and req
1. Fix code formatting issues with CodeSniffer, Drupal standard (linters should run automatically upon trying to commit).
1. Commit your changes. Each commit should be logically atomic (e.g. module adds in one commit, config in another, custom code in additional logical commits), and your commit messages should follow the pattern: "VACMS-123: A grammatically correct sentence starting with an action verb and ending with punctuation."
_Example: VACMS-1234 Add configuration for menu reduction._
1. Push work to your fork of the repository so a Pull Request may be created
`git push myfork <branchname>`
1. Push work in your branch to the remote repository so a Pull Request may be created
`git push origin <branchname>`
1. Once your PR is merged it will be automatically deployed to staging.cms.va.gov. If it is merged before 2:30pm ET and tests pass it will be in the daily, scheduled deploy to prod.cms.va.gov at 3:30pm ET.

While working on your own branch, you may have to rebase it on main which will make it out of sync with your remote branch and will require you to force push to your branch.

### When is it ok to do a force push (-f)?

On the upstream repo, never. On your own fork, it is perfectly acceptable to do force pushes. If you have recently rebased your branch on main, you may have to do a force push to your fork. When in doubt, ask in Slack.
It is never ok to force push to the main branch or an integration branch where other folks may be working from. On your own branch, it is perfectly acceptable to do force pushes. If you have recently rebased your branch on main, you may have to do a force push to your branch. When in doubt, ask in Slack.

### Pull Request Norms
* Pull requests should be made against the `main` branch.
Expand Down

0 comments on commit 020c297

Please sign in to comment.