Attempting simplest possible GitHub repo

[Elaine Byrne]

Hi CodeRanchers

I’m trying to rehabilitate my attempts at getting into a software apprenticeship-type position, and, though I have some tiny programs up on my bare-bones ‘website’, which I include in my CV etc., I’ve succumbed to the mantra that one must put stuff up on GitHub. So I made my first foray into git & GitHub, via NetBeans (don’t judge me!), a few days ago, setting up a repo for my latest tiny program  https://github.com/embyr333/NotAgain

Despite looking around quite a bit at other peoples repos, and for basic GitHub introductions, I feel I still don’t have a clue whether what I currently have on the site after pushing my NetBeans project includes irrelevant items or does not include necessary items, or both (probably the latter).

On my simple website (linked from my account profile), I offer the NotAgain program for anyone who wants to run it in a zipped folder containing three items: binary JARs for NotAgain and the external JNativeHook library (a ‘dependency’?) it uses, plus a text file “WordleSolutions” which it also needs (also called a dependency, or not?). I also offer my single source code file in a separate link (along with previous iterations, which form my pre-git versioning history). I plan to commit versions (if any) to git, and to push the changes to GitHub if I feel I’m producing something follows basic expectations for the site.

So maybe the simplest thing would be to just have NotAgain.java and WordleSolutions.txt present and add a link to the JNativeHook.jar in my README file? I get the impression that uploading the actual binaries for external libraries (dependencies) is not good form. Then, for moment forget about the option to generate a ‘release’...I assume this would require encoding the link to the dependency in a way that a build tool (e.g. Maven) would produce, but this seems to be a whole other level of complexity that seems inappropriate for my very small/simple programs(?)

Thanks to anyone who’s read this far, and further gratitude to anyone who may offer thoughts!

[Elaine Byrne]

Oops - it seemed I had to choose between ~4 sub-categories within Open Source, and I've probably chosen the wrong one (didn’t realise JForum was a ‘thing’ before clicking on that!    ), so admin/mods please feel free to move my previous post

[Elaine Byrne]

(Thanks for transferring!)

[Stephan van Hulst]

Elaine Byrne wrote:I feel I still don’t have a clue whether what I currently have on the site after pushing my NetBeans project includes irrelevant items or does not include necessary items, or both (probably the latter).

Here's a simple guideline: You should commit everything that is needed to build or document your project, except stuff that can be gotten from other repositories. Don't commit more than that. In particular, binaries that result from your build should not be committed.

Of course, it's not as cut and dry as that, but that's the basic principle. Here are some caveats:

Dependencies in general should not be committed. However, if it's difficult to get a specific version of a dependency (or you don't trust the dependency to be publicly available consistently) then you can commit it to your repository.

IDE-specific project files are usually separated into general project configuration and user-specific configuration files. Commit general project configuration. Don't commit user-specific configuration.

Don't commit environment-specific configuration files, especially not if they contain sensitive data such as passwords, private keys or tokens.

On my simple website (linked from my account profile), I offer the NotAgain program for anyone who wants to run it in a zipped folder containing three items: binary JARs for NotAgain and the external JNativeHook library (a ‘dependency’?)

GitHub offers the possibility to add releases to your repository. These are separate from your source code commits. That way you have a centralized place for people to download different versions of the build result of your application, which might be just a zip with binaries or it might be an installer or whatever else you want.

it uses, plus a text file “WordleSolutions” which it also needs (also called a dependency, or not?)

This is called a "resource". Any static file that your application needs at runtime that is not compiled code (such as images, scripts, configuration, data) is typically called an application resource. Resources should be committed to your repository.

and to push the changes to GitHub if I feel I’m producing something follows basic expectations for the site.

The point of Git is not only that your source code is versioned, but also that it is stored in a decentralized manner, so that when your development system goes up in flames, you still have a backup of the source code. Nobody expects a GitHub repo to be perfectly curated. Development is messy.

A Git mantra that you might have heard before is "commit early, commit often". Well, that also applies to pushing commits. Use development branches to push whatever you want, and then you can always curate your commit history later when you merge to a release branch.

So maybe the simplest thing would be to just have NotAgain.java and WordleSolutions.txt present and add a link to the JNativeHook.jar in my README file? I get the impression that uploading the actual binaries for external libraries (dependencies) is not good form. Then, for moment forget about the option to generate a ‘release’...I assume this would require encoding the link to the dependency in a way that a build tool (e.g. Maven) would produce, but this seems to be a whole other level of complexity that seems inappropriate for my very small/simple programs(?)

Honestly, I think a Maven POM IS the easiest way you can set up a repository. That way anybody who clones your repo has everything they need to build and run it, and for small projects Maven POMs can also be really simple.

[Elaine Byrne]

Thanks Stephan. I'll change to a stripped-down set for immediate use as I mentioned, then try the Maven overlay via NetBeans to get the pom file and switch to that if it works out.

[Elaine Byrne]

(I’ve now made a provisional ‘simplified’ repo of the type I was wondering about above, at https://github.com/embyr333/embyr333-NotAgain_simple_GH_repo))

[Elaine Byrne]

(Sorry, don’t want to seem to be bumping the thread, but just wanted to update that I now have just a single repo for NotAgain, https://github.com/embyr333/NotAgain, with the ‘simplified’ 3-item content in case anyone else visits and finds dead/altered links. Have a bit better feel for the process now, after experimenting further. Thanks for help   )

[Stephan van Hulst]

A few comments:

Readme files should just be called README.md. That way, GitHub will display it immediately without you having to explicitly click on it in the file browser.

Projects on GitHub should contain a build definition. I assume you're still working on this, but I expect most Java projects to contain a Maven POM.

Java classes should be in a named package, never the default package.

Use conventional names for your classes.

You might want to reorganize your directory structure if you're going to turn your project into a Maven project.

For example, if your NotAgain class is actually named com.example.fiveletters.FiveLetterWordsApplication, your project should have the following directory structure:
src/  main/    java/      com/        example/          fiveletters/            FiveLetterWordsApplication.java    resources/      com/        example/          fiveletters/            WordleSolutions.txt pom.xml README.md

[Elaine Byrne]

Aha, I didn’t realise that about the README – I probably would have wondered at some point why it didn’t appear by default as it had in a previous versions (when I did indeed have the name  as just “README”!) (I changed later to avoid the possibility of confusing myself with the README file generated by NetBeans in the dist directory after doing a build, but in retrospect that was unnecessary, so I will gladly revert the name.)

Re build definition: I do have a note in the README about intending to try to use Maven to generate a POM, so I will bite the bullet on that next (new to this aspect).

Re lack of package structure: yes, I realise this is not standard, and actually have a note in the comments at the top of the java file about another reason why I might want to do that. To be honest, since my projects have been so small it’s always seemed like overkill to use packages, with all the extra clicking involved in opening subdirectories, but I will probably add that also.

I’ll bear your example in mind when I try the Maven project setup (I don’t yet have a feeling for the extra levels of directory organisation needed, but will read up.)

Thanks again – really appreciate this advice!

[Stephan van Hulst]

Elaine Byrne wrote:since my projects have been so small it’s always seemed like overkill to use packages, with all the extra clicking involved in opening subdirectories, but I will probably add that also.

It sure may feel that way, but it's good to get into the habit. There are some subtle difficulties that may arise when you use the default package, so it's better to always put your classes in a named package.

For inspiration, you might use the URLs of your projects on GitHub. For instance, the base package of your application could be com.github.embyr333.notagain.

I don’t yet have a feeling for the extra levels of directory organisation needed, but will read up.

Maven uses "convention over configuration". The more your project conforms to Maven's expectations, the less you have to configure in the project descriptor. You can use whatever directory structure you like, but then you'd have to spend a lot of time configuring Maven so it builds your project correctly.

Using the directory structure I proposed above (but instead of com.example.fiveletters I'll be assuming com.github.embyr333.notagain as your application package from now on), your Maven POM could be as simple as this:
<?xml version="1.0" encoding="UTF-8"?> <project  xmlns              = "http://maven.apache.org/POM/4.0.0"  xmlns:xsi          = "http://www.w3.org/2001/XMLSchema-instance"  xsi:schemaLocation = "http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" >  <modelVersion>4.0.0</modelVersion>  <groupId>com.github.embyr333</groupId>  <artifactId>notagain</artifactId>  <version>0.1.0-SNAPSHOT</version>  <dependencies>    <dependency>      <groupId>com.github.kwhat</groupId>      <artifactId>jnativehook</artifactId>      <version>2.2.2</version>    </dependency>  </dependencies> </project>
There's a lot more you should configure (such as the Java version you're using and the versions of the Maven plugins you're using to build the project), but the POM above is a good illustration of how simple Maven can be.

If you use Maven's default directory layout, it expects your application's source code to be in the src/main/java folder. The src/main/resources folder is used for files that your application needs as runtime, but don't need to be compiled.

I put the WordleSolutions.txt file in the same package as the main application class, because in general you want resources to be in the same package as the class that uses them. That way they can easily be loaded from your application like this:

static List<String> loadWordList() {
  try (
    var stream = FiveLetterWordsApplication.class.getResourceAsStream("WordleSolutions.txt");
    var scanner = new Scanner(stream, StandardCharsets.UTF_8);
  ) {
    List<String> words = new ArrayList<>();
      
    scanner.useDelimiter("\\s*,\\s*");
    scanner.forEachRemaining(words::add);
      
    return words;
  }

  catch (IOException ex) {
    throw new AssertionError(ex);
  }
}

[Elaine Byrne]

Thanks!

[Tim Holloway]

Just the executive summary of Stephan's detailed wisdom:

If I, living on the other side of the planet, can download a copy of your project (via either git clone or as a ZIP) and built a working copy, then you've included everything you need to. If you can delete files and/or directories from the git archive and I can still build it, then you've included an optimal set.

Incidentally, in Maven projects, you should omit (.gitignore) the target directory entirely. Everything under that directory is supposed to be a product of the Maven build, including the target directory itself.

Also, properly speaking, while /src/main/resources is the standard location for general Java projects such as JARs, for webapps, the proper place for webapp resources is /src/main/webapp. The /src/main/resources directory technically defines resources that copy to the classpath, and for JARs, the classpath is the root of the JAR. In webapps, however. the classpath is under /WEB-INF/classes and /WEB-INF/lib and a WAR's resources include extra-classpath resources such as web page templates, CSS, Javascript files and so forth.

Now, regardless, the actual files and directories found in both /src/main/resources and /src/main/webapp are going to be copied to the root of the target archive when Maven does a build, but it's better, semantically speaking (and in case of future changes) to use /src/main/webapp for WARs. You may also see unexpected effects if you are building at a finer grained Maven goal level, such as "war:war".

[Elaine Byrne]

Thanks, Tim!

[Stephan van Hulst]

Elaine, I opened a pull request that converts your project to a Maven project.

You are free to commit changes to the pull request before you merge it, but if you don't intend to merge it, let me know so I can remove my fork.

[Elaine Byrne]

Thanks Stephan! I think I've merged it. (I meant to make an associated change to the README, but I'll have to do that later.) To get it back into my IDE (NetBeans) I think I would do Team > Remote > Pull (or Pull from Upstream)? (I tried initially to make a clone into a new project folder, but that didn't work.) (On a related note, I did try making a Maven test project, but the build process did not complete, so I'm also not sure if there's something amiss with my set generally)

[Stephan van Hulst]

Yes, pull from upstream should work (as long as you don't have uncommitted changes).

The very minimal POM I showed you earlier in this topic uses a very old Java version by default, which is likely the problem. The POM I added to your project initially used Java 17, but when I noticed that you had mentioned Java 8 somewhere in your README, I downgraded the Java version in the POM. I also set the plugins that Maven uses by default to a fixed version, which is good practice.

NetBeans should automatically recognize your project as a Maven project. When you build it, NetBeans will call Maven internally. Ensure that you have NetBeans configured to use a recent version of Maven.

[Elaine Byrne]

Netbeans Teels > Plugins > Maven > Installed tab shows
Version: 4.30.1
Source: NetBeans IDE 8.1 (Build 201510222201)

but looking on the Maven site suggests 3.8.6 is the latest version?, so I’m uncertain.

(Then doing a Check for Updates bring up a “Unable to connect to the Plugin Portal because of Connection reset” warning)

Maybe I’ll just go ahead with the pull and see what happens

[Stephan van Hulst]

You're using a really old version of NetBeans. It might be time to upgrade to version 14.

Normally I'd recommend you download the latest version of Maven (which currently is version 3.8.6) and configure that in NetBeans, but NetBeans 14 comes bundled with Maven 3.8.5, which is recent enough.

[Elaine Byrne]

Ah, thanks. I know this sounds cowardly, but I think I’ll have to delay doing that until I’m in a better situation – I’m operating in isolation, with an unreliable laptop, and I can’t afford the risk of having to something going wrong. But I really appreciate you having pointed me in the right direction for future explorations!

[Stephan van Hulst]

Note that you can easily run two different NetBeans versions side-by-side. When downloading NetBeans, just select the ZIP option instead of the Installer option.

Here is a shortcut: https://www.apache.org/dyn/closer.cgi/netbeans/netbeans/14/netbeans-14-bin.zip

After extracting the ZIP in some installation location and open the etc/netbeans.conf file in a text editor. Uncomment the netbeans_jdkhome line and set the location of your JDK. For instance, for me it looks like this:
netbeans_jdkhome="C:/Program Files/OpenJDK/jdk-18.0.1.1"
That reminds me, if you're not already on Java 17 or higher, this might also be a good opportunity to download a new version of Java.

Another shortcut: http://jdk.java.net/18/

Finally, to run NetBeans you just run one of the executables in the bin/ folder. After NetBeans opens, I usually just pin the window to my taskbar.

Installing and running NetBeans this way should not interfere with your existing installation, so if you don't like NetBeans 14 you can just go back to using the old version.

[Elaine Byrne]

Thanks!