Skip to content
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

Principles version in markdown may not match current revision viewed #20

Closed
scottrigby opened this issue Sep 15, 2021 · 0 comments · Fixed by #21
Closed

Principles version in markdown may not match current revision viewed #20

scottrigby opened this issue Sep 15, 2021 · 0 comments · Fixed by #21
Labels
bug Something isn't working
Milestone

Comments

@scottrigby
Copy link
Member

Good initial idea

The principles version was added to the header in markdown so that, when printed (and hung in every tech office in the world!), it will be clear which version of the principles is on view.

New problem

However, the problem is that in-between releases the last version is still part of the markdown header even as new changes are approved and merged into main. Take a look at this oneline commit history sample from today:

Screen Shot 2021-09-15 at 4 29 54 PM

You can see there are 4 commits after tag v0.1.0 which a user could view that still contain # GitOps Principles v0.1.0 at the top of PRINCIPLES.md.

Recommended fix

Remove principles version from header markdown in main to a separate commit in release branches. Can be manual at first then automated.

@scottrigby scottrigby added the task Basic task label Sep 15, 2021
scottrigby added a commit that referenced this issue Sep 15, 2021
Signed-off-by: Scott Rigby <scott@r6by.com>
@scottrigby scottrigby added this to the v1.0.0-rc.1 milestone Sep 15, 2021
@scottrigby scottrigby changed the title Move principles version may be incorrect in markdown depending on the current revision Principles version in markdown may not match current revision viewed Sep 15, 2021
@scottrigby scottrigby added bug Something isn't working and removed task Basic task labels Sep 15, 2021
@scottrigby scottrigby mentioned this issue Sep 15, 2021
2 tasks
scottrigby added a commit that referenced this issue Sep 17, 2021
First release candidate drafted by GWG/OGO chairs, incorporating all discussion
and feedback thus far. The objective was to propose a release candidate draft
reconciling and incorporating the varying views of all GitOps Working Group
community participants.

This draft has now been reviewed by GitHub WG maintainers. It was also reviewed
by GitOps Working Group members, including members of the principles committee.
After merge, we will create a release branch and tag the release. The goal is
to publish RC 1 widely, to request async feedback from the WG principles
committee, the wider WG, people listed in the interested-parties document:
https://github.com/gitops-working-group/gitops-working-group/blob/main/interested-parties.md
and the wider GitOps community.

This draft addresses previously planned milestones (now closed):

- Simplify principles titles
- Clarify language to emphasize main point of each principle
- Incorporate all community feedback with broad consensus
- Resolve notes and glossary items
- Ensure consistency of language
- Ensure accessibility of all language

RC 1 PR drafted by:
Co-authored-by: Scott Rigby <scott@r6by.com>
Co-authored-by: Dan Garfield <dan@todaywasawesome.com>
Co-authored-by: Leonardo Murillo <leonardo@weave.works>

RC 1 PR reviewed by:
Co-authored-by: Nicholas Thomson <RedbackThomson@users.noreply.github.com>
Co-authored-by: William Caban <william.caban@gmail.com>
Co-authored-by: Dan Garfield <dan@todaywasawesome.com>
Co-authored-by: Moshe Immerman <moshe@flanksource.com>
Co-authored-by: Chris Sanders <csand@microsoft.com>
Co-authored-by: Leonardo Murillo <leonardo@weave.works>
Co-authored-by: Carlos Santana <csantana23@gmail.com>

This draft was also based on work by the GitOps WG over the past 6 months.
Specifically #14, which was closed in favor of this RC 1 draft. Contributors
to that PR were:

Co-authored-by: Jesse Butler <butlerjl@amazon.com>
Co-authored-by: William Caban <william.caban@gmail.com>
Co-authored-by: Dan Garfield <dan@todaywasawesome.com>
Co-authored-by: Moshe Immerman <moshe@flanksource.com>
Co-authored-by: Christian Hernandez <christian@redhat.com>
Co-authored-by: Leonardo Murillo <leonardo@weave.works>
Co-authored-by: Scott Rigby <scott@r6by.com>
Co-authored-by: Chris Sanders <csand@microsoft.com>
Co-authored-by: Roberth Strand <me@robstr.dev>
Co-authored-by: Daniel Warner <daniel.warner@codefresh.io>
Co-authored-by: Florian Heubeck <Heubeck@mediamarktsaturn.com>
Co-authored-by: Lloyd Chang <lloydchang@gmail.com>

Signed-off-by: Scott Rigby <scott@r6by.com>

Review changes after the initial draft were:

* Moving glossary to separate file, and adding hyperlinks from principles to
  glossary items

* Added context sentence for the principle headers grammar

* Removed incomplete summary from introduction. Unecessary now because
  principles are shorter and summmarize themselves

* Moved glossary to a standalone file

* Linked terms in principles to now linkable glossary items

* Address markdown version / git revision mismatch. Fixes #20

* Typo fixes

Co-authored-by: Nicholas Thomson <nithomso@amazon.com>

* Added note about configuration data excluding other external data

Co-authored-by: Nicholas Thomson <RedbackThomson@users.noreply.github.com>

* Fixed formatting of software system glossary item. Clarified one list item

Co-authored-by: Nicholas Thomson <nithomso@amazon.com>

* Added links within glossary items

Co-authored-by: Dan Garfield <dan@todaywasawesome.com>

* Broadened user data example to just database contents. Fix formatting

Co-authored-by: Dan Garfield <dan@todaywasawesome.com>

* Remove 'versioned' from reconciliation glossary item.

Co-authored-by: Dan Garfield <dan@todaywasawesome.com>

* Fixed grammar, capitalization, and other formatting

Co-authored-by: Dan Garfield <dan@todaywasawesome.com>

Signed-off-by: Scott Rigby <scott@r6by.com>
todaywasawesome pushed a commit that referenced this issue Sep 24, 2021
First release candidate drafted by GWG/OGO chairs, incorporating all discussion
and feedback thus far. The objective was to propose a release candidate draft
reconciling and incorporating the varying views of all GitOps Working Group
community participants.

This draft has now been reviewed by GitHub WG maintainers. It was also reviewed
by GitOps Working Group members, including members of the principles committee.
After merge, we will create a release branch and tag the release. The goal is
to publish RC 1 widely, to request async feedback from the WG principles
committee, the wider WG, people listed in the interested-parties document:
https://github.com/gitops-working-group/gitops-working-group/blob/main/interested-parties.md
and the wider GitOps community.

This draft addresses previously planned milestones (now closed):

- Simplify principles titles
- Clarify language to emphasize main point of each principle
- Incorporate all community feedback with broad consensus
- Resolve notes and glossary items
- Ensure consistency of language
- Ensure accessibility of all language

RC 1 PR drafted by:
Co-authored-by: Scott Rigby <scott@r6by.com>
Co-authored-by: Dan Garfield <dan@todaywasawesome.com>
Co-authored-by: Leonardo Murillo <leonardo@weave.works>

RC 1 PR reviewed by:
Co-authored-by: Nicholas Thomson <RedbackThomson@users.noreply.github.com>
Co-authored-by: William Caban <william.caban@gmail.com>
Co-authored-by: Dan Garfield <dan@todaywasawesome.com>
Co-authored-by: Moshe Immerman <moshe@flanksource.com>
Co-authored-by: Chris Sanders <csand@microsoft.com>
Co-authored-by: Leonardo Murillo <leonardo@weave.works>
Co-authored-by: Carlos Santana <csantana23@gmail.com>

This draft was also based on work by the GitOps WG over the past 6 months.
Specifically #14, which was closed in favor of this RC 1 draft. Contributors
to that PR were:

Co-authored-by: Jesse Butler <butlerjl@amazon.com>
Co-authored-by: William Caban <william.caban@gmail.com>
Co-authored-by: Dan Garfield <dan@todaywasawesome.com>
Co-authored-by: Moshe Immerman <moshe@flanksource.com>
Co-authored-by: Christian Hernandez <christian@redhat.com>
Co-authored-by: Leonardo Murillo <leonardo@weave.works>
Co-authored-by: Scott Rigby <scott@r6by.com>
Co-authored-by: Chris Sanders <csand@microsoft.com>
Co-authored-by: Roberth Strand <me@robstr.dev>
Co-authored-by: Daniel Warner <daniel.warner@codefresh.io>
Co-authored-by: Florian Heubeck <Heubeck@mediamarktsaturn.com>
Co-authored-by: Lloyd Chang <lloydchang@gmail.com>

Signed-off-by: Scott Rigby <scott@r6by.com>

Review changes after the initial draft were:

* Moving glossary to separate file, and adding hyperlinks from principles to
  glossary items

* Added context sentence for the principle headers grammar

* Removed incomplete summary from introduction. Unecessary now because
  principles are shorter and summmarize themselves

* Moved glossary to a standalone file

* Linked terms in principles to now linkable glossary items

* Address markdown version / git revision mismatch. Fixes #20

* Typo fixes

Co-authored-by: Nicholas Thomson <nithomso@amazon.com>

* Added note about configuration data excluding other external data

Co-authored-by: Nicholas Thomson <RedbackThomson@users.noreply.github.com>

* Fixed formatting of software system glossary item. Clarified one list item

Co-authored-by: Nicholas Thomson <nithomso@amazon.com>

* Added links within glossary items

Co-authored-by: Dan Garfield <dan@todaywasawesome.com>

* Broadened user data example to just database contents. Fix formatting

Co-authored-by: Dan Garfield <dan@todaywasawesome.com>

* Remove 'versioned' from reconciliation glossary item.

Co-authored-by: Dan Garfield <dan@todaywasawesome.com>

* Fixed grammar, capitalization, and other formatting

Co-authored-by: Dan Garfield <dan@todaywasawesome.com>

Signed-off-by: Scott Rigby <scott@r6by.com>
Signed-off-by: Dan Garfield <dan@todaywasawesome.com>
scottrigby added a commit that referenced this issue Oct 5, 2021
Fixes #20

Signed-off-by: Scott Rigby <scott@r6by.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Something isn't working
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant