Upgrade readme

[jcbhmr]

This PR would... (checkboxes are draft progress)

• Change the readme to be more visually appealing
• ❗ NOT change anything about the actual content of the readme (still in v3)
• Provide comments where things could go for v4 Move to organization #19 Possible to automagically use ${{ github.token }} ? #17 Consider using git subtree #18
• ❗ NOT change anything else about the project
• Has a good format for the inputs table/list

Why this is a good idea:

1. It has header image. Images are worth 1000 words
2. It has splashes of color. colors are good for human eyeballs to draw attention
3. It has more than one code example. This helps readers generalize instead of pigeonhole on a single usecase
4. It has a well-formatted table. This is personal preference of formatting.

[jcbhmr]

Options for the inputs:

1: table

2: In YAML

https://github.com/actions/checkout#readme

3: Literal list

https://github.com/wow-actions/contributors-list#readme

4: Headers for each option

https://github.com/veracode/veracode-sandboxes-helper#readme

5: dl description list

<dl> (couldn't find any GitHub Action examples of this)

@Andrew-Chen-Wang opinions?

[Andrew-Chen-Wang]

veracode lgtm with individual sections for paragraphs

[jcbhmr]

veracode lgtm with individual sections for paragraphs

Sounds good! 👍 Individual sections for each option it is.

[jcbhmr]

Here's a preview screnshot of what it looks like:

It's OK in my opinion... I think that it takes up a bit much vertical space, but that's my opinion.

Good enough for now though!

[Andrew-Chen-Wang]

My thoughts are: if we have a huge repository that have multiple functionalities, then it'll require quite a bit of explaining.

[jcbhmr]

btw how do I merge this? Do you have to merge it? Why does it say 1 review required? I'm a bit of a newbie

I'm assuming your "lgtm" comment is an endorsement that this PR is OK to merge... If I'm misunderstanding please correct me ❤

[jcbhmr]

Just spotted that I used my old header image from jcbhmr/deploy-wiki and didn't update the text in photosohp... I need to fix that 😆

[Andrew-Chen-Wang]

yea I set it to have at least one review required

[Andrew-Chen-Wang]

a few comments for now. A lot on my plate at the moment

[jcbhmr]

Oh and when if this is merged set the description of the repo to the same as the desc in the readme to satisfy my ocd pretty pls.

📖 GitHub Action to sync a folder to the GitHub wiki

[Andrew-Chen-Wang]

Thanks a bunch! Looks great!

[Andrew-Chen-Wang]

We don't have a terms of service. You can just keep the original notice that the repository is not affiliated with GitHub

[jcbhmr]

really i don't even know why its needed since it appears on the page sidebar as a disclaimer added by github. i just copied that into this repo since I figured you wanted it (it was already kinda there at the bottom) 🤷

https://github.com/marketplace/actions/github-wiki-action

[jcbhmr]

i don't think this is required because literally no other action does it. it's only there on github's marketplace to indicate that the github.com skin thing with github branding and stuff doesn't mean they endorse your product.

you don't need that notice in your readme though since that's already covered under other terms/conds as being yours not githubs (i think?) -- it only needs to appear added as a sidebar by the github.com/marketplace site when the readme is being presented on their own branded page, but not when its just your repo page

at least that's my understanding of it?

[Andrew-Chen-Wang]

Please keep license notice at the bottom

[jcbhmr]

isnt that in the LICENSE file tho? 🤔

and shouldn't the license thing:

Copyright [yyyy] [name of copyright owner]

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

go in the actual code files not the readme?

[jcbhmr]

actually i found an authoritative source https://infra.apache.org/apply-license.html that states

Each original source document (code and documentation, but not the LICENSE and NOTICE files) should include a short license header at the top. If the distribution contains documents not covered by an ICLA, CCLA or Software Grant (such as third-party libraries), consult the policy guide.

or https://www.apache.org/foundation/license-faq.html#Apply-My-Software

[Andrew-Chen-Wang]

Typically, all that's necessary is the LICENSE file. Putting the header in the source files are also a plus but not needed. I always have license information in the README for quick access purpose when reading through READMEs. It's fairly standard in the OSS world, perhaps not the boilerplate that I like including, but mentioning the license is always helpful

[jcbhmr]

Putting the header in the source files are also a plus but not needed.

it actually sounds like its required in the apache 2.0 license

[jcbhmr]

I've added the following license header to each code or documentation item in the repo:

Copyright 2023 Andrew Chen Wang
SPDX-License-Identifier: Apache-2.0

as stated here:

and as discussed here: open-telemetry/community#113 (comment)

[jcbhmr]

@Andrew-Chen-Wang 📬