How to Publish Your Project at GitHub

It is important for modern software developers to publish open source projects online and collaborate with other developers over the whole world. Thanks to the modern technologies includes Git and its well-known service provider GitHub, these tasks become quite easy nowadays.

This guide outlines the whole process to publish a project on GitHub. Let's start.

How-to Guide

1. Install Git

Install and setup Git in your local computer:

• Installing Git
• First-Time Git Setup

2. Initial a Local Git Repository

Under your project directory, to initial a local git repository as follows:

$ git init

3. Manage Personal Information

If you choose to make your personal information public on GitHub, you can simply configure as follows:

$ git config --global user.name '<your-name>'
$ git config --global user.email '<your-email>'

If you want to keep your personal information private on GitHub, this is the way to do so:

• sign in GitHub website, Edit profile > Personal settings > Emails, check the options "Keep my email address private" and "Block command line pushes that expose my email"
• your GitHub non-reply email will be shown in that web page
• config personal information for GitHub hosted repositories using your GitHub non-reply email:

$ git config user.name '<your-GitHub-login-name>'
$ git config user.email '<your-GitHub-nonreply-email>'

4. Manage .gitignore

Under your project directory, create a file called .gitignore that lists all files/patterns which should NOT be managed/tracked by Git (in other word, to be ignored). The different sorts of projects determine the different ignore list. Please check the following examples for references:

• GitHub - github/gitignore: A collection of useful .gitignore templates
• gitignore.io - Create Useful .gitignore Files For Your Project

5. Manage files

Add the project files to the local repository:

1. add all project files (except the ignored files) into staging area

$ git add .

2. commit the staged files

$ git commit -m '<commit message>'

6. Create a GitHub Repository

1. sign in or sign up a GitHub account
2. click the plus icon beside your login icon, and then select "New repository"
3. follow the provided instructions to fill in the required information
4. record the GitHub repository url after it is created

7. Upload your Project to GitHub

1. setup the new GitHub repository as the remote repository:

git remote add origin <github repository url>

2. upload your project files to GitHub repository (set up-stream remote as well):

git push -u origin master

8. Polish up

You may polish your GitHub repository in the following ways:

• add a file called README.md, which introduces your project to the visitors in Markdown language
• choose a appropriate license type for your project, and then add the license file into repository
• promote your project through social networks

Reference

• Git
• GitHub
• Bitbucket

How to Create a Custom Maven Archetype

Maven archetype is a powerful project template tool, which used to create various kinds of maven powered project in the much easier and faster way. Sometime, we prefer to create our own templates to help the our specific works with maven. It is not hard but the good guide could be tricky to locate online. So I make this quick start guide to help the impatient people.

Simple Process

The easy method I found is as follows:

1. create/locate a sample java maven project, which is what your archetype will generate later. Let us call the chosen sample project as target project
2. create archetype from target project. Under target project, type-in the following command:

mvn archetype:create-from-project


3. the resulted archetype, let us call it custom archetype, is generated under the directory of current project:

target/generated-sources/archetype/


4. improve custom archetype in the following ways:
1. configure target/generated-sources/archetype/pom.xml to update the information about this archetype project, such group id, artifact id, version and etc. I suggest to add following code snippet into it to avoid the UTF encoding warning during the process of archetype generate:

  <properties>
    <project.build.sourceencoding>UTF-8</project.build.sourceencoding>
  </properties>

2. configure target/generated-sources/archetype/src/main/resources/META-INF/maven/archetype-metadata.xml to setup which directories & files should be generated, and default properties if needed, see more details
3. modify the source file templates of target project if you like. These template files may contain the property placeholders powered by Velocity. You can locate them under the following directory:

target/generated-sources/archetype/src/main/resources/archetype-resources/


4. you may move the directory archetype out of target project. The directory archetype contains all files needed for custom archetype, It is an independent maven project from target project

target/generated-sources/archetype/


5. install custom archetype into your local maven repository so that you can try it. Under custom archetype directory, type-in the following command:

mvn clean install


6. test custom archetype by generating the target project from scratch. Let's assume the artifact id of your custom archetype is my-custom-archetype. Switch to another arbitrary working directory, type-in the following command:

mvn archetype:generate -Dfilter=my-custom-archetype


7. follow the instructions provided by maven, your target project should be generated under the current working directory when it complete successfully. You could start to test the resulted target project. You may repeat the step 4 to step 7 until you are satisfied with the custom archetype
8. Well done, your custom archetype is ready to work. You may choose to release it to your organization's maven repository, or open source and release to public maven repository, or simply keep using it as a secret weapon in your own machine. It is up to you. Please enjoy the efficiency boost for future development works!

Last Word

There is a alternative way to create custom archetype. You may create a sample archetype directly by using a maven built-in archetype called maven-archetype-archetype, and then progressively modify it to archive what you want. This may be a better choice under certain cases. To do this way, choose a arbitrary working directory, and type-in the following command:

mvn archetype:generate
  -DarchetypeArtifactId=maven-archetype-archetype 
  -DgroupId=[group id of your custom archetype]
  -DartifactId=[artifact id of your custom archetype]

Stack & Version

• JDK - 1.8
• Apache maven - 3.5.4
• Apache maven archetype plugin - 3.0.1

Reference

• Apache maven
• Creating an archetype from an existing project
• Youtube video - How To Create a Custom Maven Archetype (2017), 13.5 minutes
• Maven Archetype Plugin - archetype:create-from-project