Skip to content

Commit

Permalink
enhanced the syncing process and added some why not keep it simple text
Browse files Browse the repository at this point in the history
Signed-off-by: henkvancann <[email protected]>
  • Loading branch information
henkvancann committed Apr 15, 2024
1 parent 009e14f commit 2b47634
Showing 1 changed file with 28 additions and 0 deletions.
28 changes: 28 additions & 0 deletions spec/48_source_management.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,14 @@ Example given:
and using information and related information [[xref: processing]] services.
```

### Why not simply a Content Management System like Wordpress??!

1. user management in github ecosystem instead of centralized technological island creation
2. Spec-up static website generation, we don't want introduction of databases
3. Continuous Developement Continuous Integration (CDCI) versus staging by hand
4. Business rules and Permanent linking made possible via Github Actions
Just to name a few reasons.

### Who
The roles involved in the use cases are editor, production repo master and curator.
One person could have more than one role.
Expand All @@ -48,7 +56,9 @@ This is the process diagram


These are the two main options we have use cases for:

- A. Wiki based = edits WITHOUT curation and PR are possible, see 1. below

- B. PR based WITH optinal curation and **mandatory** PRs, see option 2, 3 and 4 below.

### 1. Wiki
Expand All @@ -69,16 +79,30 @@ Now `editors` can us the wiki of the target repo to CRU term definition. We desc

`Curators` could add markdown comments to the sources of the wiki.

> NB: Editing of the target github wiki repo on your local machine is possible but a rather strange way to manage sources of your terms definitions. But it can be done if you have the user rights: push the wiki repo to the target wiki repo.
> We advise to choose one of the other source management options, because it's more direct.
::: NOTE
After this source editing has been saved our solution also overwrites the repo file `/spec/splitted-dir/{term}.md` (if present) for syncing purposes.
:::

### 2. Github edit
Editors go the the term definition they want to C R U on the github.com user site of the target repo (which is controlled by master).

This way editors can edit (after having forked the target repo to their own user account) the term definition and offer a PR to master. After the PR is made the curator can comment on the changes proposed and live viewable on the user account of the editor.

::: NOTE
After this source editing have been saved our solution also overwrites the wiki repo file `/{term}.md` (if present) for syncing purposes.
:::

### 3. Terminal - text file edit

This way editors can edit (after having cloned the target repo to their own user account). He/she uses a text editor to write changes in the separate .md file of the term and definitions directory. He/she use git on the command line to add, commit and push files to their own github user account version of the target repo. From the target repo he/she creates a PR by hand for the curator and the master to assess and eventually accept or decline. After the PR is made the curator can comment on the changes proposed and live viewable on the user account of the editor.

::: NOTE
After this source editing have been saved our solution also overwrites the wiki repo file `/{term}.md` (if present) for syncing purposes.
:::

### 4. IDE
An integrated Development Environment, e.g. Visual studio Code - text file edit

Expand All @@ -89,6 +113,10 @@ The end result is a 4 options to make changes and 2 options to get the results a

All methods have full git tracing of who did what and when.

::: NOTE
After this source editing have been saved our solution also overwrites the wiki repo file `/{term}.md` (if present) for syncing purposes.
:::

### How

The rest of this chapter outlines the use cases for managing term definitions in a spec-up based specification, focusing on the roles of editors, production repo masters, and curators.
Expand Down

0 comments on commit 2b47634

Please sign in to comment.