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.

Sign up for GitHub

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

Update CLOSED_CONTRIBUTIONS.md to clarify internal contribution process #449

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3eb092e
Update CLOSED_CONTRIBUTIONS.md to clarify internal contribution process
mjang Apr 24, 2025
0315c3c
Merge branch 'main' into mjang-patch-2
ADubhlaoich Apr 24, 2025
9462e0c
Progressive disclosure of detail
mjang Apr 25, 2025
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
40 changes: 32 additions & 8 deletions CLOSED_CONTRIBUTIONS.md
View file
Open in desktop
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,53 @@ 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/`**
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.
At this prompt, you can now create a feature branch. To comply with NGINX conventions, **Ensure that you prefix all branch names with `internal/`**
Copy link
Contributor

Choose a reason for hiding this comment

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

More unnecessary information added.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Actually, this prompt is the big one that scared me.

Copy link
Contributor

Choose a reason for hiding this comment

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

My concern here is that the amount of information any one of us might find reassuring is noise to anyone else.

I don't even use this process as a result of the work I'm engaged with, but I still think it's important to keep things concise for clarity in respect to the idea that the person most likely to use this process has enough agency and knowledge to figure things out for themselves.

I would like us to start documenting more and more of our processes publicly and there is a cognitive weight to every piece of information added that is not critically important: it sets a precedent of adding more content everywhere for the sake of things that might go wrong.

This is the same reasoning as why we do our best to avoid frequently asked questions: most are assumed instead of actually asked, and they usually come down to a failure of content design or information architecture.

If we got reports from people that they needed reassurance about how git works, I would not push back on this: I never assume that because I find something confusing, everyone else does too, and as a result, try not to assume my lived experience should be what drives the direction of any given piece of documentation.


```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 +88,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