Skip to content

Commit

Permalink
docs: git contributing guide (#1892)
Browse files Browse the repository at this point in the history 
Signed-off-by: Meg McRoberts <meg.mcroberts@dynatrace.com>
  • Loading branch information
@StackScribe
StackScribe committed Aug 31, 2023
1 parent 124e243 commit 30393c6
Show file tree
Hide file tree
Showing 7 changed files with 407 additions and 279 deletions.
88 changes: 2 additions & 86 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,98 +55,14 @@ Please check [Related Technologies](docs/content/en/contribute/general/technolog

Please check [Linter Requirements](docs/content/en/contribute/docs/linter-requirements/_index.md).

## Submit a Pull Request 🚀
## Working with git

At this point, you should switch back to the `main` branch in your repository,
and make sure it is up to date with `main` branch of Keptn Lifecycle Toolkit:

```bash
git remote add upstream https://github.com/keptn/lifecycle-toolkit.git
git checkout main
git pull upstream main
```

Then update your feature branch from your local copy of `main` and push it:

```bash
git checkout feature/123/foo
git rebase main
git push --set-upstream origin feature/123/foo
```

> Note:
All PRs must include a commit message with a description of the changes made!

Make sure you **sign off your commits**.
To do this automatically check [this](https://github.com/keptn/lifecycle-toolkit/blob/main/CONTRIBUTING.md#auto-signoff-commit-messages).
Finally, go to GitHub and create a Pull Request.
There should be a PR template already prepared for you.
If not, you will find it at `.github/pull_request_template.md`.
Please describe what this PR is about and add a link to relevant GitHub issues.
If you changed something that is visible to the user, please add a screenshot.
Please follow the
[conventional commit guidelines](https://www.conventionalcommits.org/en/v1.0.0/) for your PR title.

If you only have one commit in your PR, please follow the guidelines for the message
of that single commit, otherwise the PR title is enough.
You can find a list of all possible feature types [here](#commit-types).

An example for a pull request title would be:

```bash
feat(api): New endpoint for feature X (#1234)
```
If you have **breaking changes** in your PR, it is important to note them in the PR
description but also in the merge commit for that PR.
When pressing "squash and merge", you have the option to fill out the commit message.
Please use that feature to add the breaking changes according to the
[conventional commit guidelines](https://www.conventionalcommits.org/en/v1.0.0/).
Also, please remove the PR number at the end and just add the issue number.
An example for a PR with breaking changes and the according merge commit:
```bash
feat(bridge): New button that breaks other things (#345)

BREAKING CHANGE: The new button added with #345 introduces new functionality that is not compatible with the previous type of sent events.
```
If your breaking change can be explained in a single line you can also use this form:
```bash
feat(bridge)!: New button that breaks other things (#345)
```
Following those guidelines helps us create automated releases where the commit
and PR messages are directly used in the changelog.
In addition, please always ask yourself the following questions:
**Based on the linked issue,**
**what changes within the PR would you expect as a reviewer?**
See [Working with Git](docs/content/en/contribute/general/git)

Your PR will usually be reviewed by the Keptn Lifecycle Toolkit team within a
couple of days, but feel free to let us know about your PR
[via Slack](https://cloud-native.slack.com/channels/keptn-lifecycle-toolkit-dev).

### Commit Types
**Type** can be:
* `feat`: a new feature
* `fix`: a bug fix
* `build`: changes that affect the build system or external dependencies
* `chore`: other changes that don't modify source or test files
* `ci`: changes to our CI configuration files and scripts
* `docs`: documentation only changes
* `perf`: a code change that improves performance
* `refactor`: a code change that neither fixes a bug nor adds a feature
* `revert`: reverts a previous commit
* `style`: changes that do not affect the meaning of the code
* `test`: adding missing tests or correcting existing tests
## Developer Certification of Origin (DCO)

All commits must be accompanied by a DCO sign-off.
Expand Down
194 changes: 1 addition & 193 deletions docs/CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,199 +35,7 @@ Please check [Building the Documentation Locally](content/en/contribute/docs/loc

The documentation source is stored on github.com
and you use the standard github facilities to modify it.
The following notes are provided for people who need a little help.

### Fork and clone the repository

Perform the following steps to create a copy of this repository on your local machine:

1. Fork the Keptn repository:

* Log into GitHub (or create a GitHub account and then log into it).
* Go to the [Keptn lifecycle-toolkit repository](https://github.com/keptn/lifecycle-toolkit).
* Click the **Fork** button at the top of the screen.
* Choose the user for the fork from the options you are given,
usually your GitHub ID.

A copy of this repository is now available in your GitHub account.

2. Get the string to use when cloning your fork:

* Click the green "Code" button on the UI page.
* Select the protocol to use for this clone (either HTTPS or SSH).
* A box is displayed that gives the URL for the selected protocol.
Click the icon at the right end of that box to copy that URL.

3. Run the **git clone** command from the shell of a local directory
to clone the forked repository to a directory on your local machine,
pasting in the URl you saved in the previous step:

```console
git clone https://github.com/<UserName>/lifecycle-toolkit
```

or

```console
git clone git@github.com:<UserName>/lifecycle-toolkit.git
```

Where <*UserName*> is your GitHub username.
The lifecycle-toolkit directory is now available in the local directory.

4. Associate your clone with `upstream`.
To do this, use the same string you used to clone your fork.

* Be sure that you are in the root folder of the project
and run *git status* to confirm that you are on the `main` branch.
* Type the following to associate `upstream` with your clone,
pasting in the string for the main repo that you copied above.:

```console
git remote add upstream https://github.com/keptn/lifecycle-toolkit.git
```

### Create a new branch and make your changes

Now you have your upstream setup in your local machine.
You need to create a local branch where you will make your changes.
Be sure that your branch is based on and sync'ed with `main`,
unless you intend to create a derivative PR:

The following sequence of commands does that:

```console
git checkout main
git pull upstream main
git push origin main
git checkout -b <my-new-branch>
```

Now you can make your changes, build them locally to check formatting,
then create a PR to add these changes to the documentation set

### Submitting new content through a pull request

If you have forked and cloned the repository,
you can modify the documentation or add new material
by editing the markdown file(s) in the local clone of your fork
and then submitting a *pull request (PR)*.

Note that you can also modify the source using the GitHub editor.
This is very useful when you want to fix a typo or make a small editorial change
but, if you are doing significant writing,
it is generally better to work on files in your local clone.

1. Execute the following and check the output to ensure that your branch is set up correctly:

```console
git status
```

1. Do the writing you want to do in your local branch, checking the formatted version at `localhost:1314/docs-dev`.

1. When you have completed the writing you want to do, close all files in your branch and run `git status` to confirm
that it correctly reflects the files you have modified, added, and deleted.

1. Add and commit your changes.
Here, we commit all modified files but you can specify individual files to the
`git add` command.
The `git commit -s` command commits the files and signs that you are contributing this intellectual property to the
Keptn project.

```console
git add .
git commit -s
```

Use vi commands to add a description of the PR
(should be 80 characters or less) to the commit.
The title text should be prefixed with `docs:`
to conform to our semantic commit scheme.
This title is displayed as the title of the PR in listings.
You can add multiple lines explaining the PR here but, in general,
it is better to only supply the PR title here;
you can add more information and edit the PR title
when you create the PR on the GitHub UI page.

1. Push your branch to github:
* If you cloned your fork to use SSH, the command is:

```console
git push --set-upstream origin <branch-name>
```

> **Note**
You can just issue the `git push` command.
Git responds with an error message that gives you the full command line to use; you can copy this command and
paste it into your shell to push the content.

* If you cloned your fork to use HTTP, the command is:

```console
git push <need options/arguments>
```

1. Create the PR by going to the [lifecycle-toolkit](https://github.com/keptn/lifecycle-toolkit) GitHub repository.
* You should see a yellow shaded area that says something like:

```console
<GitID>:<branch> had recent pushes less than a minute ago
```

* Click on the button in that shaded area marked:

```console
Compare & pull request
```

* Check that the title of the PR is correct; click the "Edit" button to modify it.
Add "WIP" (Work in Progress) or "Draft" to the title if the PR is not yet ready for general review.
* Add a full description of the work in the PR, including any notes for reviewers, a reference to the relevant GitHub
issue (if any), and tags for specific people (if any) who may be interested in this PR.
* Carefully review the changes GitHub displays for this PR to ensure that they are what you want.
* Click the green "Create pull request" button to create the PR.
You may want to record the PR number somewhere for future reference although you can always find the PR in the
GitHub lists of open and closed PRs.
* GitHub automatically populates the "Reviewers" block.
* If this PR is not ready for review, click the "Still in progress?
Convert to draft" string under the list of
reviewers.
People can still review the content but can not merge the PR until you remove the "Draft" status.
* The block of the PR that reports on checks will include the following item:

```console
This pull request is still a work in progress
Draft pull requests cannot be merged.
```

* When the PR is ready to be reviewed, approved, and merged, click the "Ready to review" button to remove the "Draft"
status.
Then, if you added "WIP" or "Draft" to the PR title, remove it now.

1. Your PR should be reviewed within a few days.
Watch for any comments that may be added by reviewers and implement or
respond to the recommended changes as soon as possible.

* If a reviewer makes a GitHub suggestion and you agree with the change, just click "Accept this change" to create a
commit for that modification.
You can also group several suggestions into a single commit using the GitHub tools.
* You can make other changes using the GitHub editor or you can work in your local branch to make modifications.

* If changes have been made using the GitHub editor, you will need to do a `git pull` request to pull those
commits back to your local branch before you push the new changes.
* After modifying the local source, issue the `git add .`, `git commit`, and `git push` commands to push your
changes to github.

1. When your PR has the appropriate approvals, it will be merged and the revised content should be published on the
website within a few minutes.

1. When your PR has been approved and merged,
you can delete your local branch with the following command:

```console
git branch -d <branch-name>
```
Please check [Working with Git](content/en/contribute/general/git/_index.md).

## Developer Certification of Origin (DCO)

Expand Down
22 changes: 22 additions & 0 deletions docs/content/en/contribute/general/git/_index.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
---
title: Working with Git
description: Using Git to contribute software and docs
weight: 200
---

Keptn source for software and documentation is stored in the
[Keptn lifecycle-toolkit repository](https://github.com/keptn/lifecycle-toolkit).
Contributions are made using standard Git practices.
This section describes the basic steps required to contribute using Git
and summarizes some standard practices we use with Keptn.

You can also modify the source using the GitHub editor.
This is very useful when you want to fix a typo
or make some other small change
although be sure so include the DCO signoff.

If you are doing significant work,
you should fork and clone your own copy of the repository,
make your changes in a local branch,
then push those changes to github where they can be reviewed
and ultimately merged into the product.
52 changes: 52 additions & 0 deletions docs/content/en/contribute/general/git/branch-create/_index.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
---
title: Create local branch
description: How to create a local branch and make modifications in it
weight: 30
---

After you
[fork and clone](../fork-clone)
the Keptn repository and set `upstream` in your local machine,
you need to create a local branch where you will make your changes.

## Create a new branch and make your changes

Be sure that your branch is based on and sync'ed with `main`,
unless you intend to create a derivative PR.
The following sequence of commands does that:

```console
git checkout main
git pull upstream main
git push origin main
git checkout -b <my-new-branch>
```

Execute the following and check the output
to ensure that your branch is set up correctly:

```console
git status
```

Now you can make your changes, build and test them locally,
then create a PR to add these changes to the documentation set.

* For documentation changes:
* Do the writing you want to do in your local branch
* Check the formatted version in your IDE
or at `localhost:1314/docs-dev`
to ensure that it is rendering correctly
and that all links are valid..
See [Build Documentation Locally](../../../docs/local-building)
for more information.
* Run `make markdownlint-fix` to check and fix the markdown code.

* For software changes:
* Create the new code in your local branch.
* Create and run unit tests for your new code.
* Run other appropriate test to ensure that your code works correctly.

When you have completed the checking and testing of your work,
it is time to push your changes and create a PR that can be reviewed.
See [Create PR](../pr-create) for details.

0 comments on commit 30393c6

Please sign in to comment.