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.

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

Update README.md #15

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update README.md #15

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
3 changes: 2 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,9 +35,10 @@ Thus, you can add an rss/xml feed to share stories and experiences to be present
and it will show up in the feed for the respective repository and the [aggregated blogs feed](https://hpc.social/blog/)
here. Here is how to get started, for either of the above!

1. Fork the repository that you've chosen in the step above (**you should not be forking this repository where you are reading!**), clone it to your machine, and checkout a new branch.
1. Fork the repository that you've chosen in the step above (**you should not be forking this repository where you are reading!**), checkout a new branch, and clone it to your machine.
Copy link
Contributor

Choose a reason for hiding this comment

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

Technically speaking, the first order was correct. You generally want to clone a full repository to a local machine, and then checking a new branch from the main.

Copy link
Author

Choose a reason for hiding this comment

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

But how do you push the branch to GitHub? Don't you need to have same branch on GitHub as on the local machine?

Copy link
Contributor

Choose a reason for hiding this comment

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

Not when you start! You typically want to:

  1. Fork a repository to your account
  2. Clone the fork
  3. Checkout a new branch for your feature git checkout -b add/my-blog (does not need to exist on the remote)
  4. Do the work, save changes git commit -a -s -m 'adding my blog entry
  5. And then push! git push origin add/my-blog

The reason you want to make the branch locally and have the entire repository is that your main branch should always be in sync with the upstream main branch. As an example, I usually add "upstream" to my forks:

[core]
	repositoryformatversion = 0
	filemode = true
	bare = false
	logallrefupdates = true
[remote "upstream"]
	url = [email protected]:spack/spack
	fetch = +refs/heads/*:refs/remotes/origin/*
[remote "origin"]
	url = [email protected]:flux-framework/spack
	fetch = +refs/heads/*:refs/remotes/origin/*
[branch "main"]
	remote = origin
	merge = refs/heads/main

And then when I start fresh I can update the main from upstream, and checkout from it:

# switch to my local main branch
git checkout main

# update from upstream
git pull upstream main

# checkout a new feature branch from the updated main
git checkout -b new-feature

And then way, when you open a PR to the upstream main it's always mostly up to date. You never (generally) want to push to your fork's main, because then if upstream squashes and merges (or similar) the next PR you open will have extra zombie commits that exist in your main but not upstream. And it's useful to have the main locally that is updated also for rebase, e.g.,

git rebase -i main

So TLDR this is why you want this order of steps.

Copy link
Contributor

Choose a reason for hiding this comment

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

First, just a note to agree with @vsoch on the order of steps. As a shortcut, an easy workflow for small changes is to fork the repository, edit the files you want to change online in your fork using the web editing features of the GitHub site (eithre simple editing with the "edit this file" feature or its E key shortcut, or with the GitHub Web editor as described at https://docs.github.com/en/codespaces/the-githubdev-web-based-editor for more complicated changes), commit the changes, and create a pull request based on your edited fork. The basic steps are the same as Vanessa explained above. You can also use the GitHub Desktop app on your machine if you use Mac or Windows as your desktop; again, the basic steps are the same.

Copy link
Contributor

Choose a reason for hiding this comment

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

oh indeed! Codespaces is really nice :)

Anyone that isn't comfortable with GitHub / git can also just open an issue and point us to their site and we can do a PR/update on their behalf. I have to usually clone and check the content anyway, so it's not a ton of extra todo.

1. Add your entry to the [_data/authors.yml](_data/authors.yml) file
1. Generate your set of posts (instructions below)
1. Push your change to GitHub
Copy link
Contributor

Choose a reason for hiding this comment

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

@mvanwaveren this line would be ok to add, if you want to update the PR to change the first set of changes (or just undo them) and keep this line, I think it would be a good addition. Feel free to use any of the text I provided about the process if you think there isn't enough detail.

1. Open a pull request to the main repository!

> ⚠️ **important** The blog you chose from the links above should be the one that you clone, and not the central portal repository where you are reading the instructions now.
Expand Down