Skip to content

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

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 37 additions & 8 deletions CLOSED_CONTRIBUTIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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>`
Comment on lines +44 to +52
Copy link
Contributor

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

they definitely do not need how git itself works to be re-documented.

I don't know everything about how Git works, and I've worked at GitLab.

Copy link
Contributor

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.

Copy link
Contributor Author

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.


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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Branches are not necessarily limited to features: this is an unnecessary caveat.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You did specify internal/feature in the current version of this doc

Suggested change
Change back to the origin `main` branch, create a new branch (`feature`), merge your internal branch, and push to origin.
Change back to the origin `main` branch, create a new branch "such as" (`feature`), merge your internal branch, and push to origin.

Copy link
Contributor

Choose a reason for hiding this comment

The 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 internal/example instead.

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
Expand All @@ -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.
Loading