LiviaMedeiros/magia-scenario
LiviaMedeiros
/
magia-scenario
1
0
Fork 0
Code Pull Requests Releases Activity
magia-scenario/CONTRIBUTING.md

17 KiB
Raw Permalink Blame History

Table of Contents

Preamble

This file tries to describe magia-assets contributing workflow, i.e. how it should be done in order to minimize problems/mistakes/difficulties, and how it will go if nothing bad happens.
It doesn't explain the web interface (basically you just register, fork the repo, and sometimes click green buttons).
It also doesn't explain the console interface, the ssh nor the git (if you need that first, read https://git-scm.com/doc or something).
And it doesn't explain magireco file structure... Kinda dumb&pointless tutorial tbf.

Placeholders that you must fill with your info:

  • LiviaMedeiros - your username
  • tutorial-adjustments - branch name for your updates
  • tutorial commit - commit message(s)

Bold steps are mandatory.
Italic steps are skippable but still important checks.

Init phase

You need to do this phase only once.

  1. Register, fork
    The main aka upstream repo is here: https://git.rayshift.io/kamihama/magia-assets.git

  2. Clone the forked repo

$ git clone ssh://git@git-ssh.rayshift.io:45555/LiviaMedeiros/magia-assets.git
Cloning into 'magia-assets'...
remote: Enumerating objects: 55103, done.
remote: Counting objects: 100% (55103/55103), done.
remote: Compressing objects: 100% (44549/44549), done.
Receiving objects: 100% (55103/55103), 2.85 GiB | 12.23 MiB/s, done.
remote: Total 55103 (delta 10437), reused 53803 (delta 9745), pack-reused 0
Resolving deltas: 100% (10437/10437), done.
Updating files: 100% (55730/55730), done.

Takes a while, consumes space, consumes traffic.
Also consumes traffic and some resources on the server so try to never repeat this step (i.e. make backup locally and restore it if something goes terribly wrong instead of cloning again).

  1. Go into directory
$ cd magia-assets

All of future steps are assuming that you are here, or that you're using -C /path/to/your/magia-assets and know what's goingon.

  1. Check if everything is fine
$ git status
On branch master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean
  1. Add remote upstream
$ git remote add upstream ssh://git@git-ssh.rayshift.io:45555/kamihama/magia-assets.git

You'll need that to keep the fork in sync with upstream.

  1. Check if remotes are fine
$ git remote -v
origin  ssh://git@git-ssh.rayshift.io:45555/LiviaMedeiros/magia-assets.git (fetch)
origin  ssh://git@git-ssh.rayshift.io:45555/LiviaMedeiros/magia-assets.git (push)
upstream        ssh://git@git-ssh.rayshift.io:45555/kamihama/magia-assets.git (fetch)
upstream        ssh://git@git-ssh.rayshift.io:45555/kamihama/magia-assets.git (push)

Work phase

Repeatable phase. Has four parts.

Preparation

You can do this part at any time after each upstream update just to keep it synced up; but you must do it right before starting the next part.
This part assumes that if you had some previous contributions, they are already merged into upstream/master.
And that no one else is touching the same files as you plan to.

  1. Check if everything is fine
$ git status
On branch master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean

$ git branch
* master
  1. Fetch upstream data
$ git fetch upstream
remote: Enumerating objects: 415, done.
remote: Counting objects: 100% (415/415), done.
remote: Compressing objects: 100% (55/55), done.
remote: Total 217 (delta 160), reused 215 (delta 158), pack-reused 0
Receiving objects: 100% (217/217), 10.24 MiB | 6.46 MiB/s, done.
Resolving deltas: 100% (160/160), completed with 121 local objects.
From ssh://git-ssh.rayshift.io:45555/kamihama/magia-assets
 * [new branch]        master     -> upstream/master
  1. Switch to master branch
$ git checkout master
Already on 'master'
Your branch is up to date with 'origin/master'.
  1. Merge upstream master into fork master
$ git merge upstream/master
Updating 1f93676b..eb8631e7
Fast-forward
 [thingies]
 magica/resource/download/asset/master/resource/image_native/scene/quest/anime/qb_doppel_tutorial0.png |  Bin 26324 -> 41125 bytes
 [thingies]
 magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/330541-4.json             |    2 +-
 [thingies]
 330 files changed, 60186 insertions(+), 31794 deletions(-)
  1. Check if everything is fine
$ git status
On branch master
Your branch is ahead of 'origin/master' by 1 commit.
  (use "git push" to publish your local commits)

nothing to commit, working tree clean
  1. Push synced master branch on remote
$ git push
Enumerating objects: 415, done.
Counting objects: 100% (415/415), done.
Delta compression using up to 4 threads
Compressing objects: 100% (53/53), done.
Writing objects: 100% (217/217), 10.24 MiB | 2.71 MiB/s, done.
Total 217 (delta 160), reused 217 (delta 160), pack-reused 0
remote: Resolving deltas: 100% (160/160), completed with 121 local objects.
remote:
remote: Create a new pull request for 'LiviaMedeiros:master':
remote:   https://git.rayshift.io/kamihama/magia-assets/compare/master...LiviaMedeiros:master
remote:
remote: . Processing 1 references
remote: Processed 1 references in total
To ssh://git-ssh.rayshift.io:45555/LiviaMedeiros/magia-assets.git
   1f93676b..eb8631e7  master -> master

Not a necessary step but highly recommended: otherwise your fork will look confusing in the web interface.
Ignore the link and suggestion to create PR here, it's not needed.

  1. Check if everything is fine
$ git status
On branch master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean

Branching

This is where you start your own work.

  1. Make a new branch from master.
$ git checkout -b tutorial-adjustments master
Switched to a new branch 'tutorial-adjustments'

Branch name doesn't have to be very meaningful, but it would be a good idea to make them distinct.
The most simple way to achieve that is to include creation date, e.g. adjustments-211205.

  1. Check if everything is fine
$ git branch
  master
* tutorial-adjustments

$ git status
On branch tutorial-adjustments
nothing to commit, working tree clean

Doing things

This particular part is repeatable. Do the things until you're satisfied with results. If everything went really wrong, delete the new branch and start the work phase again.

  1. Check if everything is fine
$ git status
On branch tutorial-adjustments
nothing to commit, working tree clean

At this point, checking is actually important, especially if you already committed something.

  1. Do the things.
    This part is up to you.
    In this tutorial, we'll mess up with scenarios. Let's go into magica/resource/download/asset/master/resource/scenario/json/adv/ and mess with M-Girl stories.

  2. Look at what you've done

$ git status
On branch tutorial-adjustments
Changes not staged for commit:
  (use "git add/rm <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/312092-4.json
        deleted:    magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/340013-1.json
        deleted:    magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/340013-2.json
        deleted:    magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/340013-3.json
        deleted:    magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/340013-4.json
        deleted:    magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/340013-5.json
        modified:   magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/340033-1.json
        modified:   magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/340033-2.json
        modified:   magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/340033-3.json
        modified:   magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/340033-4.json
        modified:   magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/340033-5.json
        deleted:    magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/340033-6.json

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/380221-1.json
        magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/380221-2.json

no changes added to commit (use "git add" and/or "git commit -a")

Here we did 4 things:

  • modified 1 file in Rena&Kaede (1209) story
  • accidentally deleted 6 files of Yuma (3004) story
  • replaced Yuma's files with 5 files from Oriko (4001), no one will notice
  • added 2 files in brand new Yumena Yuusa (8022) story

Looks good.

  1. Add the files
$ git add .

Now the changes are staged.

  1. Check again
$ git status
On branch tutorial-adjustments
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/312092-4.json
        deleted:    magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/340013-1.json
        deleted:    magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/340013-2.json
        deleted:    magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/340013-3.json
        deleted:    magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/340013-4.json
        deleted:    magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/340013-5.json
        modified:   magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/340033-1.json
        modified:   magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/340033-2.json
        modified:   magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/340033-3.json
        modified:   magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/340033-4.json
        modified:   magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/340033-5.json
        deleted:    magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/340033-6.json
        new file:   magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/380221-1.json
        new file:   magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/380221-2.json

Still looks good.

  1. Commit changes
$ git commit -m "tutorial commit"
[tutorial-adjustments 46e70151] tutorial commit
 9 files changed, 9 insertions(+), 4 deletions(-)
 rename magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/{340013-1.json => 340033-1.json} (100%)
 rename magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/{340013-2.json => 340033-2.json} (100%)
 rename magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/{340013-3.json => 340033-3.json} (100%)
 rename magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/{340013-4.json => 340033-4.json} (100%)
 rename magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/{340013-5.json => 340033-5.json} (100%)
 delete mode 100644 magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/340033-6.json
 create mode 100644 magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/380221-1.json
 create mode 100644 magica/resource/download/asset/master/resource/scenario/json/adv/scenario_3/380221-2.json

Of course you can omit the -m "tutorial commit" part and write commit message in a different format; or add more stuff like -S; etc.
Or maybe you repeated this step to include some missing changes to your previous commit and used --amend here? It's okay as well.
Or maybe... Nvm, everything looks great.

  1. Check if everything is fine
$ git status
On branch tutorial-adjustments
nothing to commit, working tree clean

The branch doesn't exist on remote yet so it didn't say "n commits ahead".

The repeatable part ends here, so if you want to add more changes, repeat it. Do the things until you're satisfied.

Pushing

Consider it as a point of no return.
In this tutorial example, two commits are made: tutorial commit from previous part and SNAA with some offscreen changes.

  1. Check if everything is still fine
$ git status
On branch tutorial-adjustments
nothing to commit, working tree clean
  1. Check if the history looks as intended
$ git log --oneline
caf36505 (HEAD -> tutorial-adjustments) SNAA
46e70151 tutorial commit
eb8631e7 (upstream/master, origin/master, origin/HEAD, master) 20210530-1 (#16)
[a lot of stuff]

Nothing weird here: it's the latest new commit (caf36505), then the rest of new commits (46e70151), then the latest upstream/master commit (eb8631e7), then everything else (1f93676b and so on). No unnecessary merge commits, no undoing commits, all clean.

  1. Check if the changes look as intended
$ git diff master..tutorial-adjustments
[a lot of stuff]

Third check in a row: still not mandatory, but it's still a point of no return.

  1. Push the branch
$ git push --set-upstream origin tutorial-adjustments
Enumerating objects: 40, done.
Counting objects: 100% (40/40), done.
Delta compression using up to 4 threads
Compressing objects: 100% (17/17), done.
Writing objects: 100% (28/28), 2.00 KiB | 1021.00 KiB/s, done.
Total 28 (delta 6), reused 0 (delta 0), pack-reused 0
remote:
remote: Create a new pull request for 'LiviaMedeiros:tutorial-adjustments':
remote:   https://git.rayshift.io/kamihama/magia-assets/compare/master...LiviaMedeiros:tutorial-adjustments
remote:
remote: . Processing 1 references
remote: Processed 1 references in total
To ssh://git-ssh.rayshift.io:45555/LiviaMedeiros/magia-assets.git
 * [new branch]        tutorial-adjustments -> tutorial-adjustments
Branch 'tutorial-adjustments' set up to track remote branch 'tutorial-adjustments' from 'origin'.

Great job. Now you can return to the web interface or go to the provided link (https://git.rayshift.io/kamihama/magia-assets/compare/master...LiviaMedeiros:tutorial-adjustments for this example) directly.

  1. Make a Pull Request
    Check everything again, make a new Pull Request, describe&comment it if needed.

The work phase ends here. To keep everything simple, just wait until the PR is accepted and merged into upstream/master, and then you can delete the merged branch and start the work phase again.

Note: usually, when your PR is merged "as is", it is totes safe to delete the merged branch, since it becomes a subset of upstream/master.
However, if it's accepted via "squash and merge" method, I'd recommend to keep it as the most explicit and reliable way to access the individual commit history.
One way to check the merge method is to go to upstream/master commit history. If you see the exact same commits from your branch and maybe "Merge pull request" afterwards, it was a regular merge. If you see just one brand new commit which contains your whole PR, it was squash&merge.

Tl;dr

Init phase (only once):

[register, fork]
$ git clone ssh://git@git-ssh.rayshift.io:45555/LiviaMedeiros/magia-assets.git
$ cd magia-assets
$ git remote add upstream ssh://git@git-ssh.rayshift.io:45555/kamihama/magia-assets.git

Work phase (repeating):

  • Preparation & Branching (once per contribution):
$ git fetch upstream
$ git checkout master
$ git merge upstream/master
$ git push
$ git checkout -b tutorial-adjustments master
  • Doing Things (repeating):
[mess with files]
$ git add .
$ git commit -m "tutorial commit"
  • Pushing (once per contribution):
$ git push --set-upstream origin tutorial-adjustments
[create new Pull Request]

Good luck. ◕‿‿◕