diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..0349f25 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,4 @@ +* text=auto +*.py text +*.yaml text +*.md text diff --git a/.github/workflows/shell-check.yml b/.github/workflows/shell-check.yml index 7a30596..e86885e 100644 --- a/.github/workflows/shell-check.yml +++ b/.github/workflows/shell-check.yml @@ -1,8 +1,5 @@ -on: - push: - branch: - - main +on: [push, pull_request] name: 'Trigger: Push action' diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..cced40e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,104 @@ +# Contributing to jitsuin-archivist # + +Thanks for taking the time to contribute to archivist-shell! + +Contributing is not limited to writing code and submitting a PR. Feel free to submit an +[issue](https://github.com/jitsuin-inc/archivist-python/issues/new/choose) or comment on an existing one +to report a bug, provide feedback, or suggest a new feature. + +Of course, contributing code is more than welcome! To keep things simple, if you're fixing a small issue, +you can simply submit a PR and we will pick it up. However, if you're planning to submit a bigger PR to implement +a new feature or fix a relatively complex bug, please open an issue that explains the change and the motivation for it. +If you're addressing a bug, please explain how to reproduce it. + +## Pull request and git commit guidance + +### Opening PRs and organizing commits + +See the documented workflow described in the README.md file detailing the sequence of +git commands required to submit a PR from a fork of this repo. + +PRs should generally address only 1 issue at a time. If you need to fix two bugs, open two separate PRs. +This will keep the scope of your pull requests smaller and allow them to be reviewed and merged more quickly. + +When possible, fill out as much detail in the pull request template as is reasonable. +Most important is to reference the GitHub issue that you are addressing with the PR. + +**NOTE:** GitHub has +[a feature](https://docs.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) +that will automatically close issues referenced with a keyword (such as "Fixes") by a PR or commit once the PR/commit is merged. +Don't use these keywords. We don't want issues to be automatically closed. We want our testers to independently verify and close them. + +Generally, pull requests should consist of a single logical commit. +However, if your PR is for a large feature, you may need a more logical breakdown of commits. +This is fine as long as each commit is a single logical unit. + +### Writing good commit messages +Git commit messages should explain the how and why of your change and be separated into a brief subject line +followed by a more detailed body. When in doubt, follow this guide for good commit messages and +you can’t go wrong: https://chris.beams.io/posts/git-commit/. + +One particularly useful point made in the above guide is regarding commit subject lines: + +> A properly formed Git commit subject line should always be able to complete the following sentence: +> +> - If applied, this commit will your subject line here + +A simple but effective convention to follow for commits is the “problem / solution” pattern. It looks like this: +``` + + +Problem: + +Solution: +``` + +As an example, here is a commit taken from the rancher/rancher repo: +``` +commit b71ce2892eecb7c87a5212e3486f1de899a694aa +Author: Dan Ramich +Date: Tue Jun 19 11:56:52 2018 -0700 + + Add Validator for RoleTemplate + + Problem: + Builtin RoleTemplates can be updated through the API + + Solution: + Add a Validator to ensure the only field that can be changed on a + builtin RoleTemplate is 'locked' +``` + +### Reviewing, addressing feedback, and merging +Generally, pull requests need two approvals from maintainers to be merged. + +When addressing review feedback, it is helpful to the reviewer if additional changes are made in new commits. +This allows the reviewer to easily see the delta between what they previously reviewed and the changes you added +to address their feedback. These commits should be in the form of 'fixups' ('git commit --fixup HEAD'). + +Once a PR has the necessary approvals, it can be merged. + +Here’s how the merge should be handled: +- Once approved the author will be asked to squash all fixup commits generated by the review process. +- Commits and their messages should be consistent - each commit in the PR should form a logical unit with working code. +- The first change requested by a Jitsuin reviewer will be to reorganise the commits into a clean logical structure. +- The smaller a PR the more likely and more easily that the change will be approved. +- Any changes requested by a reviewer should be committed as a 'fixup' commit against the original commit in the PR. +- Once approval is granted any 'fixup' commits should be merged into their respective commits using 'git rebase -i --autosquash'. + +## Developer Certificate Of Origin ## + +To contribute to this project, you must agree to the Developer Certificate of Origin (DCO) for each commit you make. +The DCO is a simple statement that you, as a contributor, have the legal right to make the contribution. + +See the [DCO](DCO) file for the full text of what you must agree to. + +To signify that you agree to the DCO for a commit, you add a line to the git +commit message: + +```txt +Signed-off-by: Jane Smith +``` + +In most cases, you can add this signoff to your commit automatically with the +`-s` flag to `git commit`. Please use your real name and a reachable email address. diff --git a/README.md b/README.md index 9261464..5d59aad 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # archivist-shell -Repository for convenience scripts for the Jitsuin Archivist system +Repository for convenience scripts for the Jitsuin Archivist system. # Development @@ -8,11 +8,73 @@ Repository for convenience scripts for the Jitsuin Archivist system Required tools for this repo are task-runner and shellcheck. -Install task runner: https://github.com/go-task/task -Install shellcheck: https://github.com/koalaman/shellcheck#user-content-installing + - Install task runner: https://github.com/go-task/task + - Install shellcheck: https://github.com/koalaman/shellcheck#user-content-installing ## Workflow +### Preparation + +Reference: https://gist.github.com/Chaser324/ce0505fbed06b947d962 + +Fork the repo using the 'Fork' dialog at the top right corner of the github UI. + +Clone the new fork into your local development environment (assuming your github +login is 'githubUserHandle'): + +> Note: all references to 'git@github.com' assume that your local github user has adequate +> rights. If using ~/.ssh/config to manage ssh identities then replace all mentions of +> 'git@github.com' with the clause name in ~/.ssh/config which references the appropriate +> ssh key:: +> +> For example: +``` +Host ssh-githubUserHandle + User git + Hostname github.com + PreferredAuthentications publickey + IdentityFile ~/.ssh/id_rsa_githubUserHandle + +Host ssh-otherUserHandle + User git + Hostname github.com + PreferredAuthentications publickey + IdentityFile ~/.ssh/id_rsa_otherUserHandle + +Host * + IdentitiesOnly yes + +``` +> i.e. 'githubUserHandle' viz: +> +> git clone ssh-githubUserHandle:githubUserHandle/archivist-shell.git +> + + +```bash +mkdir githubUserHandle +cd githubUserHandle +git clone ssh-githubUserHandle:githubUserHandle/archivist-shell.git +``` + +Enter the new cloned fork and add the original upstream repo as a remote: + +```bash +cd archivist-shell +git remote add upstream ssh-githubUserHandle:jitsuin-inc/archivist-shell.git +git remote -v +``` + +Now add a branch for your proposed changes: + +```bash +git status +git checkout -b dev/githubUserHandle/some-proposed-fix +git status +``` + +### Making changes + To see what options are available simply execute: ```bash @@ -25,4 +87,95 @@ Make a change to the code and validate the changes: task check ``` +### Seeking a review + +#### Synchronizing the upstream + +Bring in latest changes from upstream: + +```bash +git fetch upstream +git checkout main +git pull --rebase upstream main +git checkout dev/githubUserHandle/some-proposed-fix +git rebase -i --autosquash main +``` +> Caveat +> +> Note that we are rebasing to pull in upstream changes. This assumes that +> the branch is only accessed/written by one person. If the branch is +> collaborative the better option is to 'git merge main' as this is +> safer but pollutes the git history with merge commits. +> See https://www.atlassian.com/git/tutorials/merging-vs-rebasing#the-golden-rule-of-rebasing +> +> This caveat applies to all occurrences of 'git rebase' in this document. + + +Ensure that your email and name are correct: + +```bash +git config user.name +git config user.email +``` + +#### Pushing changes upstream + +Add all changes to a commit using the **example-commit** file as a template +for the commit message. + +```bash +git add . +git commit +``` + +Push the changes upstream(the set-upstream option is only required the first time this is executed): + +```bash +git push --set-upstream origin dev/githubUserHandle/some-proposed-fix +``` + +Enter the github ui at https://github.com/jitsuin-inc/archivist-shell and +generate a pull request. + +Reviewers will be notified when a PR is generated and you will receive feedback. +Reviewers will trigger QC checks on your code. Failure will result in +automatic rejection. + +#### Making further changes + +If changes are requested push the changes as a fixup: + +```bash +git add . +git commit --fixup HEAD +git push +``` + +#### Removing Fixups After Reviewer Approval + +Eventually the reviewer(s) will approve your changes. At this point you must +squash all your fixups after syncing upstream: + +```bash +git fetch upstream +git checkout main +git pull --rebase upstream main +git checkout dev/githubUserHandle/some-proposed-fix +git rebase -i --autosquash main +git push -f +``` + +#### PR is merged. + +The reviewer will then merge your PR into main. + +At this point one must tidy up the local fork: + +```bash +git fetch upstream +git checkout main +git pull +git log +git branch -d dev/githubUserHandle/some-proposed-fix +``` diff --git a/example-commit b/example-commit new file mode 100644 index 0000000..09afe51 --- /dev/null +++ b/example-commit @@ -0,0 +1,10 @@ +A meaningful concise title + +Problem: +Clear succinct statement of problem. + +Solution: +Summarised description of solution. + +Signed-off-by: User Name +