-
Notifications
You must be signed in to change notification settings - Fork 60
Update CLOSED_CONTRIBUTIONS.md to clarify internal contribution process #449
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
|
@@ -24,7 +24,7 @@ The process is as follows: | |||||
- Merge the changes from the remote (Closed) repository branch with a new branch in the open repository | ||||||
- Open a new pull request in the open repository, where it can be merged | ||||||
|
||||||
You can get the URL through our internal communication channels: it will be represented in the following steps as `<closed-URL>`. | ||||||
You can get the URL through our internal communication channels: we describe it in the following steps as `<closed-url>`. | ||||||
|
||||||
## Steps | ||||||
|
||||||
|
@@ -33,29 +33,58 @@ To create closed content, add the closed repository as a remote to the main repo | |||||
```shell | ||||||
cd documentation | ||||||
git remote add internal [email protected]:<closed-url>.git | ||||||
git fetch | ||||||
git fetch --all | ||||||
``` | ||||||
|
||||||
Check out the remote `main` branch, and use it to create a feature branch. **Ensure that you prefix all branch names with `internal/`** | ||||||
<details> | ||||||
<summary>Click to review the process in detail</summary> | ||||||
|
||||||
You should now see the following messages: | ||||||
|
||||||
```text | ||||||
Fetching origin | ||||||
Fetching internal | ||||||
``` | ||||||
|
||||||
which fetches information from both the: | ||||||
|
||||||
- `documentation` repository (origin) | ||||||
- the `internal` repository at the `<closed-url>` | ||||||
|
||||||
Check out the remote `main` branch: | ||||||
|
||||||
```shell | ||||||
git checkout internal/main | ||||||
``` | ||||||
|
||||||
You'll see a prompt with the latest commit hash from the `<closed-url>` repository. You'll something like: | ||||||
|
||||||
```text | ||||||
documentation git:(16340b12) | ||||||
``` | ||||||
|
||||||
It's a good sign. With that hash, you're now working from the `main` branch of the `<closed-url>` repository. | ||||||
</details> | ||||||
|
||||||
You can now create a feature branch. To comply with NGINX conventions, **Ensure that you prefix all branch names with `internal/`** | ||||||
|
||||||
```shell | ||||||
git checkout -b internal/feature | ||||||
``` | ||||||
|
||||||
Once you've finished with your work, commit it and push it to the internal repository: | ||||||
|
||||||
```shell | ||||||
git add . | ||||||
git commit | ||||||
git commit -m `message` | ||||||
git push internal | ||||||
``` | ||||||
|
||||||
Open a pull request when you are ready to receive feedback from stakeholders. | ||||||
Open a pull request in the `<closed-url>` repository when you are ready to receive feedback from stakeholders. | ||||||
|
||||||
After any iterative work, close the pull request. Since the closed repository is a mirror of the open one, we do not merge changes to it. | ||||||
After any iterative work, close the pull request. Since the closed repository is a mirror of the open one, do **not** merge changes to the mirror. | ||||||
|
||||||
Change back to the origin `main` branch, create a new branch, merge your internal branch and push to origin. | ||||||
Change back to the origin `main` branch, create a new branch (`feature`), merge your internal branch, and push to origin. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Branches are not necessarily limited to features: this is an unnecessary caveat. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. You did specify
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I used feature as an example name, but I guess that could be updated to The existence of a branch means that changes exist, and are not a guarantee the branch has anything to do with features. Feels like a yak shaving level of nuance. |
||||||
|
||||||
```shell | ||||||
git checkout main | ||||||
|
@@ -64,4 +93,4 @@ git merge internal/internal/feature | |||||
git push origin | ||||||
``` | ||||||
|
||||||
Once the content changes have been merged in the open repository, they will synchronize back to the closed repository. | ||||||
Once the content changes have been merged in the open repository, they will synchronize back to the closed repository. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Way too much information. If this document is intended purely for internal contributors, they definitely do not need how git itself works to be re-documented. Adds unnecessary noise to an otherwise concise document.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't know everything about how Git works, and I've worked at GitLab.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't either, but I know enough to get work done, which is why the document is so tightly scoped.
I put a lot of trust in the idea that the reader has a certain amount of self-sufficiency given they are using git in the first place, and that they mutually put trust in us to not lead them in the wrong direction.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This process is new to me. I need more information.
To respect your desire for a tighter scope, I've set up progressive disclosure for this section, which you can test in the branch.